KintsugiKintsugi
API reference / Get customers

Get customers

GET/v1/customers

The Get Customers API retrieves a paginated list of customers based on specified filters. This API allows searching, filtering by country and state, and sorting the results.

Authorization

x-api-keystringRequired

Your secret API key. Include it with every request.

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.

/v1/customers?search_query=<search_query>&country=<country>&page=<page>
search_querystring

Search term to filter customers by name or other details

countryCountryCodeEnum | string[]

Country code in ISO 3166-1 alpha-2 format (e.g., 'US')

Available options:AFAXALDZASADAOAIAQAGARAMAWAUATAZBSBHBDBBBYBEBZBJBMBTBOBQBABWBVBRIOBNBGBFBICVKHCMCAKYCFTDCLCNCXCCCOKMCGCDCKCRHRCUCWCYCZDKDJDMDOECEGSVGQEREESZETFKFOFJFIFRGFPFTFGAGMGEDEGHGIGRGLGDGPGUGTGGGNGWGYHTHMVAHNHKHUISINIDIRIQIEIMILITCIJMJPJEJOKZKEKIKPKRKWKGLALVLBLSLRLYLILTLUMOMGMWMYMVMLMTMHMQMRMUYTMXFMMDMCMNMEMSMAMZMMNANRNPNLNCNZNINENGNUNFMKMPNOOMPKPWPSPAPGPYPEPHPNPLPTPRQARERORURWBLSHKNLCMFPMVCWSSMSTSASNRSSCSLSGSXSKSISBSOZAGSSSESLKSDSRSJSECHSYTWTJTZTHTLTGTKTOTTTNTRTMTCTVUGUAAEGBUSUMUYUZVUVEVNVGVIWFEHYEZMZWXKZZ_EU
statestring

State or province code to filter customers

source__instring

Filter customers by source (comma-separated)

Available options:SHOPIFYAPI
connection_id__instring

Filter customers by connection ID (comma-separated)

Available options:conn_abc123conn_def456
order_bystring

Comma-separated list of fields to sort results by.

Available options:created_atstreet_1street_2citystatepostal_codecountrystatus
pageinteger
sizeinteger

Response

itemsCustomerRead[]Required
totalintegerRequired
pageintegerRequired
sizeintegerRequired
pagesintegerRequired
200

Successfully retrieved customers

401

The request is missing a valid x-api-key.

404

Entered an incorrect URL.

422

Query parameters failed validation, such as an out-of-range page number.

500

An unexpected server error occurred.

cURL
GET /v1/customers?search_query=John&country=US&page=1
-H "x-api-key: ***"
Example request
https://api.trykintsugi.com/v1/customers?search_query=John&country=US&page=1
Response
{
"items": [
{
"id": "cust_123abc",
"organization_id": "org_456xyz",
"name": "John Doe",
"external_id": "cust_123",
"status": "ACTIVE",
"email": "john.doe@example.com",
"phone": "+1234567890",
"street_1": "123 Main Street",
"street_2": "Apt 4B",
"city": "San Francisco",
"county": "San Francisco County",
"state": "CA",
"postal_code": "94105",
"country": "US",
"full_address": "123 Main Street, Apt 4B, San Francisco, CA 94105",
"source": "BIGCOMMERCE",
"connection_id": "conn_12345",
"address_status": "UNVERIFIED",
"external_friendly_id": "1234567890"
}
],
"total": 1,
"page": 1,
"size": 50,
"pages": 1
}