Getting Started

Validate your first address in under a minute.

Overview

The Addresspenny API lets you validate mailing addresses programmatically. Submit a raw address string and get back a standardized, parsed address with component-level validation results powered by Google Maps Address Validation.

The API is RESTful, uses JSON request and response bodies, and authenticates with Bearer tokens.

1. Get your API token

Create an API token from the API Tokens page. Each token is tied to your user account and can access any account you belong to.

Keep your token secure — treat it like a password. If a token is compromised, revoke it and create a new one.

2. Find your account ID

All API requests are scoped to an account. Your account ID is a prefixed identifier that looks like acct_1a2b3c.

You can retrieve your account IDs via the API:

curl -H "Authorization: Bearer your_api_token" \
  https://addresspenny.com/api/v1/accounts

3. Validate your first address

Submit an address for validation:

curl -X POST https://addresspenny.com/api/v1/accounts/acct_1a2b3c/addresses \
  -H "Authorization: Bearer your_api_token" \
  -H "Content-Type: application/json" \
  -d '{"address": {"original_input": "1600 Amphitheatre Pkwy, Mountain View, CA"}}'

The address is created with a pending status while validation runs in the background. This typically completes within a few seconds.

{
  "address": {
    "id": 1,
    "original_input": "1600 Amphitheatre Pkwy, Mountain View, CA",
    "status": "pending",
    "created_at": "2026-03-31T12:00:00Z",
    "updated_at": "2026-03-31T12:00:00Z"
  }
}

4. Check the result

Fetch the address to see the validation result. Once the status changes from pending to validated, the remote_payload contains the full result:

curl -H "Authorization: Bearer your_api_token" \
  https://addresspenny.com/api/v1/accounts/acct_1a2b3c/addresses/1
{
  "address": {
    "id": 1,
    "original_input": "1600 Amphitheatre Pkwy, Mountain View, CA",
    "status": "validated",
    "remote_payload": {
      "address": {
        "city": "Mountain View",
        "line1": "1600 Amphitheatre Pkwy",
        "line2": null,
        "state": "CA",
        "country": "US",
        "postal_code": "94043-1351"
      },
      "is_valid": true,
      "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043-1351, 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": "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"
  }
}

See the API Reference for a full breakdown of the response fields.

Next steps

  • Authentication — token management, email/password auth, and security best practices
  • API Reference — full endpoint documentation with response field descriptions
  • Error Handling — credit management and handling error responses