Resolve Address

GET /api/external/companies/{companyId}/resolve-address?address=<freeform> Pre-flight utility for FMV1 integrators. Geocodes a freeform address string and returns the structured sub-fields (street, city, state, county, country, zipCode) in the shape FMV1 rating expects. Most often used to derive county when upstream data does not include it. The endpoint is read-only — writes are not enriched automatically. Call this before constructing your create/update payload.

Why this exists

FMV1 enforces strict completeness on Address object-primitive values: if any sub-field is missing, the write is rejected. county is the sub-field most often missing from upstream sources. This endpoint fills that gap.

Request

Parameter	In	Required	Description
`companyId`	path	yes	Your company UUID
`address`	query	yes	Freeform address string. Must be non-empty and non-blank (whitespace-only values are rejected)

curl -G "https://app.aiinsurance.io/api/external/companies/<YOUR-COMPANY-ID>/resolve-address" \
  -H "Authorization: <YOUR-API-KEY>" \
  --data-urlencode "address=350 5th Ave, New York, NY"

Required permission: company:read

Response — `200 OK`

Returns the Address object primitive — all six sub-fields populated.

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

zipCode is always returned as a string with leading zeros preserved (e.g. "02140"). The response shape is identical to the FMV1 Address sub-object — paste the response straight into a create/update payload’s address field.

Failure behavior

If geocoding succeeds but any required sub-field cannot be determined, the endpoint returns 400 with a distinct problemCode — partial addresses are never returned as success. Branch on problemCode to know which sub-field was the problem.

HTTP	`problemCode`	Meaning
400	`BlankString`	Input was empty or whitespace-only
400	`AddressNotFound`	Geocoder returned no results — provide a more specific input
400	`AddressMissingStreet`	No street number/route in the result
400	`AddressMissingCity`	No locality / postal town / sublocality in the result
400	`AddressMissingState`	No `administrative_area_level_1` in the result
400	`AddressMissingCounty`	No `administrative_area_level_2` in the result — most common cause is an under-specified input
400	`AddressMissingCountry`	No country in the result
400	`AddressMissingZipCode`	No postal code in the result
502	`GeocodingFailed`	Upstream geocoder is unreachable or returned an error — retry after a short delay

{
  "error": {
    "code": "AddressMissingCounty",
    "message": "Resolved address is missing a county. Provide a more specific address that includes a county."
  }
}

Object Primitives → Address — full sub-field reference.
V1 API Changelog — strict Address validation was rolled out on 2026-04-28.

Overview Resolve Address

⌘I

Getting Started

Exposures

Events

Event Financials

Policies

Submissions

Quotes

Rating

Custom Objects

Configuration Management

Basic Policies

Company Files

Document Generation

Submission Parsing

Address Tools

Reference

Why this exists

Request

Response — `200 OK`

Failure behavior

​Why this exists

​Request

​Response — 200 OK

​Failure behavior

​Related

Why this exists

Request

Response — `200 OK`

Failure behavior

Related