> ## 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 > 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` ## OpenAPI ````yaml /openapi/generated-external-api.yaml get /api/external/companies/{companyId}/resolve-address openapi: 3.0.3 info: title: AI Insurance External API description: External API for AI Insurance platform version: 1.0.0 contact: email: support@aiinsurance.io servers: - url: https://app.aiinsurance.io description: Production security: - ApiKeyAuth: [] paths: /api/external/companies/{companyId}/resolve-address: get: tags: - Address summary: Resolve Address description: > 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` operationId: resolveAddress parameters: - $ref: '#/components/parameters/companyId' - name: address in: query required: true schema: type: string minLength: 1 description: | Freeform address string to geocode. Must be non-empty and non-blank (whitespace-only values are rejected). responses: '200': description: Address resolved successfully into all six subfields content: application/json: schema: $ref: '#/components/schemas/ResolveAddressResponse' examples: success: summary: US street address resolved value: street: 350 5th Avenue city: New York state: NY county: New York County country: United States zipCode: '10001' leadingZeroZip: summary: Zip code with leading zero preserved value: street: 1 Main Street city: Cambridge state: MA county: Middlesex County country: United States zipCode: '02140' '400': description: | Bad Request — the input was empty/blank, geocoding returned no results, or one of the required subfields could not be determined. Branch on `problemCode` to know which condition was hit. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: blankAddress: summary: Empty or whitespace-only address value: error: code: BlankString message: address must not be blank addressNotFound: summary: No matching geocode result value: error: code: AddressNotFound message: >- Could not find a matching address. Provide a more specific address string. missingCounty: summary: County could not be determined value: error: code: AddressMissingCounty message: >- Resolved address is missing a county. Provide a more specific address that includes a county. missingZipCode: summary: Zip code could not be determined value: error: code: AddressMissingZipCode message: >- Resolved address is missing a zip code. Provide a more specific address. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '405': description: Method Not Allowed — only `GET` is supported on this path content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: methodNotAllowed: summary: Non-GET method value: error: code: METHOD_NOT_ALLOWED message: Method POST not allowed '500': $ref: '#/components/responses/InternalServerError' '502': description: | Bad Gateway — the upstream geocoding provider failed. The request is well-formed; retry after a short delay. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: geocodingFailed: summary: Upstream geocoder error value: error: code: GeocodingFailed message: Failed to geocode the address. Please try again later. components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: ResolveAddressResponse: allOf: - $ref: '#/components/schemas/Fmv1Address' description: > Structured address resolved from a freeform input string. Shape matches the FMV1 `Address` object primitive — the endpoint returns a `400` rather than a partial address when any sub-field (including `county`) cannot be determined. ErrorResponse: type: object description: Standard error response for all external API endpoints required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable error code example: VALIDATION_ERROR message: type: string description: Human-readable error message example: 'submissionId: Required field is missing' details: type: array description: Additional details for validation errors (field-level errors) items: type: object properties: field: type: string description: The field that caused the error example: submissionId message: type: string description: Description of the field error example: Required field is missing Fmv1Address: type: object description: > Field Model V1 object primitive representing a structured postal address. All sub-fields are required when this object is provided in a write payload. Omit the parent field entirely if you do not have a complete address — partial values are rejected with `400`. Use `GET /api/external/companies/{companyId}/resolve-address` to derive a complete address (including `county`) from a freeform input string. required: - street - city - state - county - country - zipCode properties: street: type: string description: Street number and route (e.g. "350 5th Avenue") city: type: string description: City or locality (e.g. "New York") state: type: string description: | State or first-order administrative region. For US addresses this is the 2-letter postal code (e.g. "NY"). county: type: string description: County or second-order administrative area (e.g. "New York County") country: type: string description: Country name (e.g. "United States") zipCode: type: string description: | 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' responses: Unauthorized: description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingApiKey: summary: Missing API key value: error: code: UNAUTHORIZED message: Authorization header is required bearerTokenNotAllowed: summary: Bearer token used instead of API key value: error: code: UNAUTHORIZED message: External API endpoints require API key authentication Forbidden: description: Forbidden - Insufficient permissions content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: insufficientPermissions: summary: Insufficient permissions value: error: code: FORBIDDEN message: Insufficient permissions to perform this action InternalServerError: description: Internal Server Error - Unexpected error occurred content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internalError: summary: Unexpected server error value: error: code: INTERNAL_ERROR message: An unexpected error occurred. Please try again later. securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: >- API key authentication. Include your API key in the Authorization header. ````