Create customer

POST /api/account/integration/kyc/customer

Creates a customer — the persistent record of one person in your account. Call this the first time you verify someone, store the returned customer_id, and reuse it for every transaction that person ever runs.

Reusing customer_id is what enables face comparison against the enrolled face and consistency checks against previously extracted document data. Creating a new customer per verification silently disables both.

Request

string

required

Bearer {access_token} — see Authentication.

string

required

Your own identifier for this person — a user id, an account number, whatever you key on. Returned back to you on the response and useful for reconciliation.

string

The person’s email address. Optional.

string

The person’s phone number in E.164 format, for example +5491122334455. Optional.

string

A photo of the person’s face. Optional. When provided, the customer is created with an enrolled reference face, which is treated as valid. Later transactions compare the captured face against it.Send the plain base64 of the image file: standard alphabet, without a data:image/...;base64, prefix and without line breaks. JPEG or PNG only, up to 4 MB before encoding. Other formats, such as HEIC or WebP, are rejected.

Response

string (UUID)

The chmod identifier for this person. Persist this.

string

Echoed back from the request.

string (ISO-8601)

When the customer was created.

Example

curl -X POST https://{your-api-host}/api/account/integration/kyc/customer \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "external_customer_id": "user_84213",
    "email": "ana@example.com",
    "phone_number": "+5491122334455"
  }'

const res = await fetch(`${CHMOD_API_URL}/api/account/integration/kyc/customer`, {
  method: "POST",
  headers: {
    Authorization:  `Bearer ${accessToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_customer_id: user.id,
    email:                user.email,
    phone_number:         user.phone,
  }),
});

const { customer_id } = await res.json();
await db.users.update(user.id, { chmodCustomerId: customer_id });

res = requests.post(
    f"{CHMOD_API_URL}/api/account/integration/kyc/customer",
    headers={"Authorization": f"Bearer {access_token}"},
    json={
        "external_customer_id": str(user.id),
        "email":                user.email,
        "phone_number":         user.phone,
    },
)
customer_id = res.json()["customer_id"]

Response

{
  "external_customer_id": "user_84213",
  "customer_id": "4a63b11c-803d-4126-bf91-d5f8290ff0a5",
  "created_at": "2026-09-10T14:22:00.000Z"
}

Errors

A 400 on this endpoint means nothing was created. See Errors for the response body.

Cause	What to do
A customer with this `external_customer_id` already exists in your account	Reuse the `customer_id` you stored when you created it. Do not retry.
`face_reference_image` is not valid base64, is not a JPEG or PNG, or is larger than 4 MB	Fix the image and send the request again.

Customer status

Every customer carries a status that chmod maintains, and it participates in the analysis of every transaction:

Status	Effect on a transaction
`ACTIVE`	Normal. No issue emitted.
`SUSPICIOUS`	A `CUSTOMER_SUSPICIOUS` warning is emitted. Does not change the decision.
`BLOCKED`	A `CUSTOMER_BLOCKED` rejection is emitted. The transaction is `REJECTED`.

Create transaction

Open a verification for this customer and get the SDK token.

Getting Started

Customers

Transactions

Transaction configuration

Results

Create customer

Request

Response

Example

Errors

Customer status

Next

Create transaction

​Request

​Response

​Example

​Errors

​Customer status

​Next

Create transaction

Request

Response

Example

Errors

Customer status

Next