Check an address entered by hand

Checks address parts entered by hand, as the Check address action of an address field does. The server asks the address provider for the formatted address and returns a match only when the provider's address has the same postal code and city and, when given, the same street and house number, compared without case, accents and common street abbreviations. The match keeps the input's line2 and carries a candidateToken: write it as {"kind":"address","candidateToken":"…"} to store the suggested address as verified, or write the parts as {"kind":"address","value":{…}} to keep them unverified. Input without a postal code or city returns no match. 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 check changes nothing.

POST
/v1/addresses/verify

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/verify" \  -H "Content-Type: application/json" \  -d '{    "street": "Hauptstr. 5",    "postalCode": "68259",    "city": "Mannheim",    "countryCode": "de"  }'
{
  "available": true,
  "attribution": "string",
  "match": {
    "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