Skip to main content
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 system-object 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

ParameterInRequiredDescription
companyIdpathyesYour company UUID
addressqueryyesFreeform 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 system object — 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.
HTTPproblemCodeMeaning
400BlankStringInput was empty or whitespace-only
400AddressNotFoundGeocoder returned no results — provide a more specific input
400AddressMissingStreetNo street number/route in the result
400AddressMissingCityNo locality / postal town / sublocality in the result
400AddressMissingStateNo administrative_area_level_1 in the result
400AddressMissingCountyNo administrative_area_level_2 in the result — most common cause is an under-specified input
400AddressMissingCountryNo country in the result
400AddressMissingZipCodeNo postal code in the result
502GeocodingFailedUpstream 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."
  }
}