> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Resolve Address

> Geocode a freeform address string into the FMV1 Address object-primitive shape — including county.

`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](/api-v1-reference/object-primitives/overview#address): 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) |

```bash theme={null}
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](/api-v1-reference/object-primitives/overview#address) — all six sub-fields populated.

```json theme={null}
{
  "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              |

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

***

## Related

* [Object Primitives → Address](/api-v1-reference/object-primitives/overview#address) — full sub-field reference.
* [V1 API Changelog](/api-v1-reference/changelog) — strict `Address` validation was rolled out on 2026-04-28.