API Reference

Authentication

The Addresspenny API uses Bearer token authentication. Include your API token in the Authorization header with every request.

Authorization: Bearer your_api_token

You can create and manage API tokens from the API Tokens page. See the Authentication guide for details.

Base URL

https://addresspenny.com/api/v1

All endpoints are scoped to an account: /api/v1/accounts/:account_id/...

Addresses

Validate an address

Submits an address for validation. The address is created with a pending status while validation runs asynchronously in the background. Fetch the address again to check when the result is ready.

POST /api/v1/accounts/:account_id/addresses

Request body:

{
  "address": {
    "original_input": "30 rockefeller plaza new york ny"
  }
}

The original_input can be a full or partial address as a single string. The validation service will parse and standardize it.

Response: 201 Created

{
  "address": {
    "id": 1,
    "original_input": "30 rockefeller plaza new york ny",
    "status": "pending",
    "created_at": "2026-03-31T12:00:00Z",
    "updated_at": "2026-03-31T12:00:00Z"
  }
}

Get an address

Returns a single address. Once validation completes, the remote_payload contains the full result.

GET /api/v1/accounts/:account_id/addresses/:id

Response: 200 OK

{
  "address": {
    "id": 1,
    "original_input": "30 rockefeller plaza new york ny",
    "status": "validated",
    "remote_payload": {
      "address": {
        "city": "New York",
        "line1": "30 Rockefeller Plaza",
        "line2": null,
        "state": "NY",
        "country": "US",
        "postal_code": "10112-0015"
      },
      "is_valid": false,
      "original_address": {
        "city": "",
        "lines": ["30 rockefeller plaza new york ny"],
        "state": "",
        "country": "US",
        "postal_code": ""
      },
      "formatted_address": "30 Rockefeller Plaza, New York, NY 10112-0015, USA",
      "validation_results": {
        "messages": [
          {
            "code": "street_number.confirmed",
            "text": "Street number confirmed",
            "type": "info",
            "source": "google_maps"
          },
          {
            "code": "route.confirmed",
            "text": "Route confirmed",
            "type": "info",
            "source": "google_maps"
          },
          {
            "code": "locality.confirmed",
            "text": "Locality confirmed",
            "type": "info",
            "source": "google_maps"
          },
          {
            "code": "postal_code.confirmed",
            "text": "Postal code confirmed",
            "type": "info",
            "source": "google_maps"
          }
        ],
        "granularity": "premise"
      }
    },
    "created_at": "2026-03-31T12:00:00Z",
    "updated_at": "2026-03-31T12:00:05Z"
  }
}

List addresses

Returns all addresses for the account, most recent first.

GET /api/v1/accounts/:account_id/addresses

Response: 200 OK

{
  "addresses": [
    {
      "id": 2,
      "original_input": "350 Fifth Avenue, New York, NY",
      "status": "pending",
      "created_at": "2026-03-31T12:01:00Z",
      "updated_at": "2026-03-31T12:01:00Z"
    },
    {
      "id": 1,
      "original_input": "30 rockefeller plaza new york ny",
      "status": "validated",
      "remote_payload": { "..." : "..." },
      "created_at": "2026-03-31T12:00:00Z",
      "updated_at": "2026-03-31T12:00:05Z"
    }
  ]
}

Response fields

Address object

id — unique address identifier
original_input — the raw string you submitted
status — pending, validated, or failed
remote_payload — validation results (only present when validated)
created_at / updated_at — timestamps

Validation payload

The remote_payload contains the parsed and validated address data:

is_valid — whether the address is fully deliverable. An address can have all components confirmed but still be false if something is missing (e.g., an apartment or suite number).
formatted_address — the standardized, single-line address
address — the parsed address components (line1, line2, city, state, postal_code, country)
original_address — how the validation service interpreted your raw input before processing
validation_results.messages — component-level confirmation or warning messages from Google Maps, each with a code, text, and type (info, warning, or error)
validation_results.granularity — how precisely the address was matched: premise (exact building), sub_premise (unit level), route (street level only), etc.

Address status

pending — validation is in progress (typically completes in a few seconds)
validated — validation complete, remote_payload contains results
failed — validation could not be completed (e.g., service unavailable)

Errors

The API returns structured error objects with a code and message.

Insufficient credits (402)

Returned when the account has no remaining address credits. Each validation consumes one credit.

{
  "error": {
    "code": "insufficient_credits",
    "message": "No address credits remaining",
    "credits_remaining": 0,
    "credits_limit": 50
  }
}

Validation failed (422)

Returned when the request body is invalid.

{
  "error": {
    "code": "validation_failed",
    "message": "Original input can't be blank"
  }
}

Unauthorized (401)

Returned when the API token is missing or invalid.