cURL

curl -X POST https://app.instantcompliance.ai/api/v1/customers \
  -H "Authorization: Bearer ic_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "externalId": "crm-7741",
    "fullName": "Jane Doe",
    "email": "jane@example.com"
  }'

{
  "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"
}

Customers

Create or upsert a customer

Ingest an individual customer. The record is created with kyc_status = NOT_STARTED and added_via = INTEGRATION. No KYC is triggered and no credits are charged — your back-office team triggers verification from inside Instant Compliance.

Idempotency

If external_id is supplied and already exists in your organisation, the existing record is updated and the response is 200 OK.
If only email matches an existing record (and the existing record has no conflicting external_id), the record is updated and returned with 200 OK.
Otherwise a new record is created and returned with 201 Created.

Include an Idempotency-Key header to make network retries safe for 24 hours.

POST

customers

cURL

curl -X POST https://app.instantcompliance.ai/api/v1/customers \
  -H "Authorization: Bearer ic_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "externalId": "crm-7741",
    "fullName": "Jane Doe",
    "email": "jane@example.com"
  }'

{
  "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"
}

Ingest an individual customer. The record lands in your organisation tagged INTEGRATION with kyc_status = NOT_STARTED. No KYC is triggered. No credits are charged. Your back-office team completes the risk questions in-app and starts verification when ready.

Idempotent upsert behaviour

Input	Match found?	Result	Status
`externalId` supplied	Yes (same org)	Update existing record	`200 OK`
`externalId` supplied	No, but `email` matches an existing record with no `externalId`	Adopt + update	`200 OK`
`externalId` supplied	No, but `email` matches an existing record with a different `externalId`	Reject	`409 conflict`
`externalId` not supplied	`email` matches an existing record	Update existing record	`200 OK`
Neither matches	—	Create new	`201 Created`

This lets a Zapier “Create / Update Customer” action send the same event repeatedly without creating duplicates.

Retry safety

Pass Idempotency-Key (a UUID or any string ≤ 255 chars). Repeated calls with the same key within 24 hours replay the original response. See Idempotency.

Authorizations

Authorization

string

header

required

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

Headers

Idempotency-Key

string

Caller-supplied unique key for safe retries. Repeat the same key within 24 hours and we replay the original response instead of repeating the side effect. Reusing the key with a different request body returns 409 idempotency_conflict.

Maximum string length: 255

Body

application/json

fullName

string

required

Required string length: 1 - 255

string<email>

required

Maximum string length: 255

externalId

string

Your CRM identifier. Strongly recommended for idempotent upsert + round-tripping.

Maximum string length: 255

type

enum<string>

v1 only ingests individuals. Entity types ship in v2.

Available options:

INDIVIDUAL,

SOLE_TRADER

phone

string | null

Maximum string length: 32

risk

object

Optional risk pre-answers. Your back-office team will complete the full risk assessment in-app before triggering KYC; these values seed it.

Show child attributes

Response

Existing customer updated (idempotent upsert).

string<uuid>

required

Instant Compliance customer UUID.

type

enum<string>

required

v1 only ingests individuals. Entity types ship in v2.

Available options:

INDIVIDUAL,

SOLE_TRADER

full_name

string

required

kyc_status

enum<string>

required

Available options:

NOT_STARTED,

PENDING,

IN_PROGRESS,

VERIFIED,

FAILED,

NOT_REQUIRED,

AWAITING_RESUBMISSION

aml

object

required

Show child attributes

added_via

enum<string>

required

How the record entered Instant Compliance.

Available options:

ADMIN_MANUAL,

AI_EXTRACTED,

CONTACT_PORTAL,

BULK_IMPORT,

INTEGRATION,

SYSTEM

created_at

string<date-time>

required

updated_at

string<date-time>

required

external_id

string | null

string<email> | null

kyc_started_at

string<date-time> | null

kyc_completed_at

string<date-time> | null

identity

object

Populated only when kyc_status = VERIFIED. Deliberately minimal — full date of birth and full address are never exposed.

Show child attributes

API reference List customers

⌘I

​Idempotent upsert behaviour

​Retry safety

Authorizations

Headers

Body

Response

Idempotent upsert behaviour

Retry safety