KintsugiKintsugi

Suggest addresses for many inputs

POST/addresses/suggestions/bulk

Return suggestions for a batch of addresses in one request, one group per input correlated by the id you send. Every input always comes back as a group, in request order; a group has an empty suggestions list when there are no matches, the country is unsupported, or the validation service was unavailable for it.

Authorization

Api-KeystringRequired

Your secret API key. Include it with every request.

Headers

Api-Versiondate

Release date, as YYYY-MM-DD. Defaults to 2026-07-21.

Organization-Idstring

Target organization id (Organization-Id selector).

Connection-Idstring

Target connection id; resolves to its organization.

Entity-Idstring

Platform entity id; resolves to a connection's organization.

Entity-Sourcestring

Optional source to disambiguate an Entity-Id.

Body

addressesBulkAddressSuggestionsItem[]Required

The addresses to fetch suggestions for.

Response

idstring

The id from the matching request address; empty if none was sent.

suggestionsAddressSuggestion[]Required

Suggested addresses for this input; empty when there are none.

200

Successful Response

400

The request was invalid.

401

Authentication failed or was missing.

403

The credential is not permitted for this request.

404

The requested resource was not found.

409

The request conflicts with existing state.

422

The request failed validation.

cURL
POST /addresses/suggestions/bulk
-H "Api-Key: ***"
-H "Api-Version: 2026-07-21"
{
"addresses": [
{
"id": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"connectionId": "conn_2mNpQr7Ls8f3k",
"street1": "123 Main St",
"street2": "Suite 400",
"city": "San Francisco",
"county": "San Francisco County",
"state": "CA",
"postalCode": "94107",
"country": "US",
"fullAddress": "123 Main St, San Francisco, CA 94107, US"
}
]
}
Response
[
{
"id": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"suggestions": [
{
"city": "San Francisco",
"county": "San Francisco County",
"state": "CA",
"postalCode": "94107",
"country": "US"
}
]
}
]
Suggest addresses for many inputs (2026-07-21) | Kintsugi API Reference