Look up postal addresses

Finds postal addresses for free text, as the Search address box of an address field does: a street with house number and city, a postal code and city, or the name of a place. Each candidate carries its formatted address parts, the map location and a candidateToken. Write {"kind":"address","candidateToken":"…"} to an address field through /v1/records/mutate to store that candidate as a verified address; the token is valid for 24 hours and only in this workspace. Any other address write is stored as unverified, so a client cannot mark an address verified itself. countryCode limits the results to one country; without it, addresses in the caller's country come first. Show the attribution with the results. The server asks the address provider on the caller's behalf, so the provider never sees the caller's IP address or session. When the operator has not configured ADDRESS_LOOKUP_URL, nothing leaves the server and available is false. Requests are limited to 30 per user in 10 seconds (429 addressLookupRateLimited), and a provider that does not answer within 2 seconds returns 422 addressLookupUnavailable.

Requires: an active member of the workspace; no record permission, because a lookup changes nothing.

POST
/v1/addresses/lookup

Authorization

apiKeyAuth
x-api-key<token>

API key authentication. Create an API key in your user profile and include it in the x-api-key header.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://customermates.com/api/v1/addresses/lookup" \  -H "Content-Type: application/json" \  -d '{    "query": "Hauptstraße 5, Mannheim",    "countryCode": "de",    "limit": 5  }'
{
  "available": true,
  "attribution": "string",
  "candidates": [
    {
      "candidateToken": "string",
      "name": "string",
      "address": {
        "street": null,
        "line2": null,
        "postalCode": null,
        "city": null,
        "region": null,
        "countryCode": null,
        "formatted": "",
        "location": null,
        "verification": {
          "status": "unverified",
          "provider": null,
          "checkedAt": null
        }
      }
    }
  ]
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
{
  "error": {
    "kind": "validation",
    "issues": [
      {
        "code": "string",
        "path": [
          "string"
        ],
        "message": "string",
        "customCode": "recordNotFound",
        "entitlement": "string"
      }
    ],
    "retryable": true
  }
}
Empty