Resolve Address

Geocodes a freeform address string and returns the structured subfields (street, city, state, county, country, zipCode) in the shape Field Model V1 rating expects.

Intended as a pre-flight utility: integrators call this before constructing create/update payloads so addresses include all required pieces (especially county, which is required for rating but often missing from upstream systems). Writes are not auto-enriched — this endpoint is read-only.

Strict response contract. If geocoding succeeds but any required subfield cannot be determined, the endpoint returns a 400 with a distinct problemCode rather than a partial address. Integrators can branch on the problemCode to know which field was missing.

zipCode is always returned as a string with leading zeros preserved (e.g. "02140").

Required permission: company:read

GET /api/external/companies/{companyId}/resolve-address

Resolve Address

cURL

curl --request GET \
  --url https://app.aiinsurance.io/api/external/companies/{companyId}/resolve-address \
  --header 'Authorization: <api-key>'

200

success

{
  "street": "350 5th Avenue",
  "city": "New York",
  "state": "NY",
  "county": "New York County",
  "country": "United States",
  "zipCode": "10001"
}

Authorizations

Authorization · string · header · required

API key authentication. Include your API key in the Authorization header.

Path Parameters

companyId · string<uuid> · required

Company identifier

Query Parameters

address · string · required

Freeform address string to geocode. Must be non-empty and non-blank (whitespace-only values are rejected).

Minimum string length: 1

Response

200

application/json

Address resolved successfully into all six subfields

Structured address resolved from a freeform input string. Shape matches the FMV1 Address system object — the endpoint returns a 400 rather than a partial address when any sub-field (including county) cannot be determined.

street · string · required

Street number and route (e.g. "350 5th Avenue")

city · string · required

City or locality (e.g. "New York")

state · string · required

State or first-order administrative region. For US addresses this is the 2-letter postal code (e.g. "NY").

county · string · required

County or second-order administrative area (e.g. "New York County")

country · string · required

Country name (e.g. "United States")

zipCode · string · required

Postal / zip code. Must be sent as a JSON string — numeric input is rejected because JSON numbers cannot represent leading zeros (02140 parses as 2140, silently corrupting the address). Always quote ZIP codes in your payload (e.g. "02140", not 02140).

Example:

"02140"