KintsugiKintsugi
API reference / Preview addresses eligible for batch approval

Preview addresses eligible for batch approval

GET/addresses/approval-preview

Preview the addresses a batch approval would cover across every organization your credential owns; send an Organization-Id, Connection-Id or Entity-Id selector to narrow to one. status (comma-separated, default INVALID,BLANK) chooses which statuses are eligible, and limit caps the returned addresses page; totalEligible is the full count regardless of limit. The same country, has* and addressNotEmpty filters as the summary apply.

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

Narrow the request to one organization (Organization-Id selector).

Connection-Idstring

Narrow the request to a connection's organization.

Entity-Idstring

Narrow the request to a platform entity's organization.

Entity-Sourcestring

Optional source to disambiguate an Entity-Id.

Query

Every query parameter below is optional. Combine as many as you need and append them to the endpoint as a query string. The example shows a few to get you started.

/addresses/approval-preview?status=<status>&limit=<limit>&hasCountry=<hasCountry>
statusstring

Comma-separated address statuses to treat as eligible; defaults to INVALID,BLANK.

limitinteger

Maximum number of addresses to return in the preview page.

countrystring

ISO-3166 alpha-2 country code to filter by.

hasCountryboolean

Filter to addresses that do (true) or do not (false) have a country.

hasStateboolean

Filter to addresses that do (true) or do not (false) have a state.

hasCityboolean

Filter to addresses that do (true) or do not (false) have a city.

hasCountyboolean

Filter to addresses that do (true) or do not (false) have a county.

hasPostalCodeboolean

Filter to addresses that do (true) or do not (false) have a postal code.

addressNotEmptyboolean

true keeps only addresses with at least one of state, city, postal code or county; false keeps only fully empty ones.

Response

totalEligibleintegerRequired

Total addresses eligible for approval under the requested filters.

addressesTransactionAddress[]Required

First page of eligible addresses, capped by limit. totalEligible is the full count regardless of this cap.

breakdownByCountryCountryAddressCount[]Required

Eligible-address counts by country across the whole eligible set.

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
GET /addresses/approval-preview?status={status}&limit=500&hasCountry={hasCountry}
-H "Api-Key: ***"
-H "Api-Version: 2026-07-21"
Example request
https://api.trykintsugi.com/addresses/approval-preview?status={status}&limit=500&hasCountry={hasCountry}
Response
{
"totalEligible": 8,
"addresses": [
{
"id": "3f6c2b1e-8a4d-4c2e-9b1f-2d7e5a6c9f10",
"type": "BILL_TO",
"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",
"phone": "+1 415 555 0100",
"status": "UNVERIFIED"
}
],
"breakdownByCountry": [
{
"country": "US",
"count": 4
}
]
}
Preview addresses eligible for batch approval (2026-07-21) | Kintsugi API Reference