Add a customer

POST

tenants

add-user

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Carter",
    "email": "james.carter@example.com",
    "phone": "+447911123456",
    "customerId": "cus_Kq3mN8xLp2vT"
  }'

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emily Thompson",
    "email": "emily.thompson@example.com"
  }'

curl "https://api.zquence.ai/v1/tenants/add-user?environmentId=69f9b5fa0600ccbf9c677005" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Carter",
    "email": "james.carter@example.com",
    "phone": "+447911123456",
    "customerId": "cus_Kq3mN8xLp2vT"
  }'

{
  "id": "6a25cdac36bc6230704b5b59",
  "name": "James Carter",
  "email": "james.carter@example.com",
  "phone": "+447911123456",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "customerId": "cus_Kq3mN8xLp2vT",
  "status": "inactive",
  "createdAt": "2026-06-07T10:00:00.000Z",
  "updatedAt": "2026-06-07T10:00:00.000Z"
}

{
  "statusCode": 409,
  "message": "User with email james.carter@example.com already exists with a different phone"
}

{
  "statusCode": 400,
  "message": "email is required"
}

Creates a new customer record. phone is optional. Idempotent on email, and on phone when provided: if a user with the same email (and, when you send one, the same phone) already exists, the call succeeds, updates their environment membership, and optionally stores your customerId if they don’t have one yet.

Sync behavior

Scenario	Result
New email + new/no phone	Customer created. `201 Created`.
Existing email + matching phone (exact match)	Customer synced — environment membership updated, `customerId` stored if not already set. `200 OK`.
Existing email + different phone	`409 Conflict` — email already exists with a different phone number.
Existing email, no phone sent this call	Customer synced — treated as a match on email alone, not a phone conflict. `200 OK`.
Existing phone + different email	`409 Conflict` — phone already exists with a different email.

Note: when phone is omitted from a call, dedup for that call falls back to email only — Zquence can’t detect a phone conflict it was never told about. Send phone on every call if you want strict dedup across both fields.

Query parameters

string

Place the new customer into this specific environment. If omitted, the environment is resolved from the authenticated API key.

Body

string

required

Full display name of the customer.

string

required

Valid RFC 5322 email address. Stored lowercase. Used as the primary deduplication key alongside phone.

string

Phone number. Optional. When provided, must be 6–30 characters — E.164 format strongly recommended (e.g. +14155552671). Normalized to E.164 on write.

string

Your system’s identifier for this customer (e.g. a CRM ID, Stripe customer ID, or database UUID). Stored as-is and returned on every customer read. Useful for correlating Zquence customers back to your own data.

On create: stored immediately.
On sync (existing user): stored only if the customer does not already have an customerId. Pass it on every sync call to ensure it is captured even if the first call didn’t include it.

Returns

string

Customer’s MongoDB ObjectId.

string

Display name.

string

Normalized lowercase email address.

string

Normalized E.164 phone number.

string

Owning tenant identifier.

string | null

Primary environment this customer belongs to.

string | null

Your system’s customer identifier, if provided.

string

"inactive" on first creation. Advances to "active" once the customer accepts a Zquence account invitation.

string

ISO 8601 UTC creation timestamp.

string

ISO 8601 UTC last-updated timestamp.

Error codes

Status	Meaning
`400`	Missing required field (`name` or `email`), invalid phone format (if `phone` was sent), or `tenantId` not resolvable.
`401`	Missing or invalid API key pair.
`409`	Email exists with a different phone, or phone exists with a different email.

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Carter",
    "email": "james.carter@example.com",
    "phone": "+447911123456",
    "customerId": "cus_Kq3mN8xLp2vT"
  }'

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emily Thompson",
    "email": "emily.thompson@example.com"
  }'

curl "https://api.zquence.ai/v1/tenants/add-user?environmentId=69f9b5fa0600ccbf9c677005" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Carter",
    "email": "james.carter@example.com",
    "phone": "+447911123456",
    "customerId": "cus_Kq3mN8xLp2vT"
  }'

{
  "id": "6a25cdac36bc6230704b5b59",
  "name": "James Carter",
  "email": "james.carter@example.com",
  "phone": "+447911123456",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "customerId": "cus_Kq3mN8xLp2vT",
  "status": "inactive",
  "createdAt": "2026-06-07T10:00:00.000Z",
  "updatedAt": "2026-06-07T10:00:00.000Z"
}

{
  "statusCode": 409,
  "message": "User with email james.carter@example.com already exists with a different phone"
}

{
  "statusCode": 400,
  "message": "email is required"
}

Webhook events

Fires tenant.users.invite on successful creation of a new customer.

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Carter",
    "email": "james.carter@example.com",
    "phone": "+447911123456",
    "customerId": "cus_Kq3mN8xLp2vT"
  }'

curl https://api.zquence.ai/v1/tenants/add-user \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Emily Thompson",
    "email": "emily.thompson@example.com"
  }'

curl "https://api.zquence.ai/v1/tenants/add-user?environmentId=69f9b5fa0600ccbf9c677005" \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "James Carter",
    "email": "james.carter@example.com",
    "phone": "+447911123456",
    "customerId": "cus_Kq3mN8xLp2vT"
  }'

{
  "id": "6a25cdac36bc6230704b5b59",
  "name": "James Carter",
  "email": "james.carter@example.com",
  "phone": "+447911123456",
  "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
  "environmentId": "69f9b5fa0600ccbf9c677005",
  "customerId": "cus_Kq3mN8xLp2vT",
  "status": "inactive",
  "createdAt": "2026-06-07T10:00:00.000Z",
  "updatedAt": "2026-06-07T10:00:00.000Z"
}

{
  "statusCode": 409,
  "message": "User with email james.carter@example.com already exists with a different phone"
}

{
  "statusCode": 400,
  "message": "email is required"
}

Introduction

Tenant

Environments

Customers

Accounts

KYC

Document reviews

Source of funds

Files

Webhooks

Sync

Sanctions

Sync behavior

Query parameters

Body

Returns

Error codes

Webhook events

​Sync behavior

​Query parameters

​Body

​Returns

​Error codes

​Webhook events

Sync behavior

Query parameters

Body

Returns

Error codes

Webhook events