Skip to main content
GET
/
customers
List customers
curl --request GET \
  --url https://app.instantcompliance.ai/api/v1/customers \
  --header 'Authorization: Bearer <token>'
{
  "object": "list",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "external_id": "crm-7741",
      "type": "INDIVIDUAL",
      "full_name": "Jane Doe",
      "email": "jane@example.com",
      "kyc_status": "VERIFIED",
      "kyc_started_at": "2026-06-23T01:00:00Z",
      "kyc_completed_at": "2026-06-23T01:12:00Z",
      "identity": {
        "verified_legal_name": "JANE DOE",
        "verified_country": "AUS"
      },
      "aml": {
        "status": "CLEAR",
        "screened_at": "2026-06-23T01:12:00Z",
        "last_reviewed_at": null,
        "flags": {
          "pep": false,
          "sanctions": false,
          "adverse_media": false,
          "terrorism": false
        }
      },
      "added_via": "INTEGRATION",
      "created_at": "2026-06-22T22:14:00Z",
      "updated_at": "2026-06-23T01:12:05Z"
    }
  ],
  "has_more": true,
  "next_cursor": "<string>",
  "limit": 123,
  "total_count": 123
}
List individual customers in your organisation. This is the primary polling source for syncing status into your CRM.

​
Polling pattern

Pass updated_since set to the timestamp of your last poll. Each call then returns only customers updated since then: 
GET /v1/customers?updated_since=2026-06-23T00:00:00Z&limit=100
Walk pages with the cursor field. See Polling for status for a robust loop, and Pagination for the cursor mechanics.

​
Filtering

Query parameterEffect
statusKYC status (e.g. IN_PROGRESS, VERIFIED).
aml_statusAML compliance status (e.g. NEEDS_REVIEW, CLEAR).
updated_sinceISO-8601 timestamp lower bound.
external_idLookup by your CRM identifier.
limit1–100. Default 50.
cursorContinuation cursor from the previous response.

​
Returned shape

Only individual customer types (INDIVIDUAL, SOLE_TRADER) are returned. Entity customers (companies, trusts, partnerships) are not exposed in v1.

Authorizations

​
Authorization
string
header
required

Bearer API key issued from Settings → Developers in your Instant Compliance organisation. Format: ic_live_….

Query Parameters

​
limit
integer
default:50

Number of records to return (1–100).

Required range: 1 <= x <= 100
​
cursor
string

Opaque cursor from the previous response's next_cursor.

​
status
enum<string>

Filter by KYC status.

Available options:
NOT_STARTED,
PENDING,
IN_PROGRESS,
VERIFIED,
FAILED,
NOT_REQUIRED,
AWAITING_RESUBMISSION
​
aml_status
enum<string>

Filter by AML compliance status.

Available options:
NOT_SCREENED,
IN_PROGRESS,
CLEAR,
NEEDS_REVIEW,
RESOLVED
​
updated_since
string<date-time>

ISO-8601 timestamp. Return only customers updated after this time.

​
external_id
string

Lookup by your CRM identifier.

​
include
enum<string>

Comma-separated list of opt-in response fields. Currently the only supported value is total_count, which adds an exact count of the filtered set to the response envelope. Costs an extra COUNT(*) query — omit it on hot polling loops.

Available options:
total_count

Response

Paginated customer list.

​
object
enum<string>
required

Always "list" for paginated envelopes.

Available options:
list
​
data
object[]
required
​
has_more
boolean
required

True if at least one more page exists. Use as the loop condition.

​
next_cursor
string | null
required

Pass as cursor on the next request, or null when no more pages.

​
limit
integer
required

The limit echoed back after defaulting/clamping (1–100, default 50).

​
total_count
integer

Total records matching the filter set (not the page). Only present when the request included include=total_count.