Add customers in bulk

POST

tenants

add-user-bulk

curl https://api.zquence.ai/v1/tenants/add-user-bulk \
  -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"
    },
    {
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "customerId": "cus_Rp7wQ2nMk4uS"
    }
  ]'

curl "https://api.zquence.ai/v1/tenants/add-user-bulk?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"
    }
  ]'

{
  "created": [
    {
      "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"
    },
    {
      "id": "6a25cdac36bc6230704b5b60",
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
      "environmentId": "69f9b5fa0600ccbf9c677005",
      "customerId": "cus_Rp7wQ2nMk4uS",
      "status": "inactive",
      "createdAt": "2026-06-07T10:00:01.000Z",
      "updatedAt": "2026-06-07T10:00:01.000Z"
    }
  ],
  "createdCount": 2,
  "skippedEmails": [],
  "skippedPhones": [],
  "skippedCount": 0
}

{
  "created": [
    {
      "id": "6a25cdac36bc6230704b5b60",
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
      "environmentId": "69f9b5fa0600ccbf9c677005",
      "customerId": "cus_Rp7wQ2nMk4uS",
      "status": "inactive",
      "createdAt": "2026-06-07T10:00:01.000Z",
      "updatedAt": "2026-06-07T10:00:01.000Z"
    }
  ],
  "createdCount": 1,
  "skippedEmails": ["james.carter@example.com"],
  "skippedPhones": [],
  "skippedCount": 1
}

{
  "statusCode": 409,
  "message": "All users already exist or conflict (emails: james.carter@example.com)"
}

{
  "statusCode": 400,
  "message": "Users array is empty"
}

Batch version of Add a customer. Applies the same idempotent sync logic per entry: existing exact-match customers are synced (environment membership updated, customerId stored if missing) while conflicting entries are skipped.

Sync behavior per entry

Scenario	Result
New email + new/no phone	Customer created, included in `created`.
Existing email + matching phone	Customer synced — environment membership updated, `customerId` stored if not already set. Included in `created`.
Existing email + different phone	Entry skipped. Email added to `skippedEmails`.
Existing email, no phone sent this entry	Customer synced — treated as a match on email alone, not a phone conflict. Included in `created`.
Existing phone + different email	Entry skipped. Phone added to `skippedPhones`.
Duplicate within the same request	Second occurrence silently deduplicated.

Note: when an entry omits phone, dedup for that entry falls back to email only — Zquence can’t detect a phone conflict it was never told about.

Query parameters

string

Assign all customers in this batch to a specific environment. If omitted, the environment is resolved from the authenticated API key.

Body

A JSON array of customer objects. Each object accepts the same fields as Add a customer.

string

required

Full display name.

string

required

Valid RFC 5322 email. Used as a deduplication key alongside phone.

string

Phone number. Optional. When provided, must be 6–30 chars — E.164 format recommended (e.g. +14155552671).

string

Your system’s identifier for this customer. Stored on create; applied to existing customers only if they don’t already have one.

Returns

array

Array of full customer objects that were newly created or successfully synced in this call.

number

Number of customers in created.

string[]

Emails that were skipped due to a conflict (existing email with a different phone).

string[]

Phone numbers that were skipped due to a conflict (existing phone with a different email).

number

Total count of distinct skipped identifiers (skippedEmails + skippedPhones deduplicated).

Error codes

Status	Meaning
`400`	Empty array, no valid entries after normalization, or `tenantId` not resolvable.
`401`	Missing or invalid API key pair.
`409`	Every entry in the batch already conflicts — no new users could be created or synced.

curl https://api.zquence.ai/v1/tenants/add-user-bulk \
  -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"
    },
    {
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "customerId": "cus_Rp7wQ2nMk4uS"
    }
  ]'

curl "https://api.zquence.ai/v1/tenants/add-user-bulk?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"
    }
  ]'

{
  "created": [
    {
      "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"
    },
    {
      "id": "6a25cdac36bc6230704b5b60",
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
      "environmentId": "69f9b5fa0600ccbf9c677005",
      "customerId": "cus_Rp7wQ2nMk4uS",
      "status": "inactive",
      "createdAt": "2026-06-07T10:00:01.000Z",
      "updatedAt": "2026-06-07T10:00:01.000Z"
    }
  ],
  "createdCount": 2,
  "skippedEmails": [],
  "skippedPhones": [],
  "skippedCount": 0
}

{
  "created": [
    {
      "id": "6a25cdac36bc6230704b5b60",
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
      "environmentId": "69f9b5fa0600ccbf9c677005",
      "customerId": "cus_Rp7wQ2nMk4uS",
      "status": "inactive",
      "createdAt": "2026-06-07T10:00:01.000Z",
      "updatedAt": "2026-06-07T10:00:01.000Z"
    }
  ],
  "createdCount": 1,
  "skippedEmails": ["james.carter@example.com"],
  "skippedPhones": [],
  "skippedCount": 1
}

{
  "statusCode": 409,
  "message": "All users already exist or conflict (emails: james.carter@example.com)"
}

{
  "statusCode": 400,
  "message": "Users array is empty"
}

curl https://api.zquence.ai/v1/tenants/add-user-bulk \
  -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"
    },
    {
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "customerId": "cus_Rp7wQ2nMk4uS"
    }
  ]'

curl "https://api.zquence.ai/v1/tenants/add-user-bulk?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"
    }
  ]'

{
  "created": [
    {
      "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"
    },
    {
      "id": "6a25cdac36bc6230704b5b60",
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
      "environmentId": "69f9b5fa0600ccbf9c677005",
      "customerId": "cus_Rp7wQ2nMk4uS",
      "status": "inactive",
      "createdAt": "2026-06-07T10:00:01.000Z",
      "updatedAt": "2026-06-07T10:00:01.000Z"
    }
  ],
  "createdCount": 2,
  "skippedEmails": [],
  "skippedPhones": [],
  "skippedCount": 0
}

{
  "created": [
    {
      "id": "6a25cdac36bc6230704b5b60",
      "name": "Emily Thompson",
      "email": "emily.thompson@example.com",
      "phone": "+14155550193",
      "tenantId": "bc41c6ab-7206-4033-b632-4d1cfa86d840",
      "environmentId": "69f9b5fa0600ccbf9c677005",
      "customerId": "cus_Rp7wQ2nMk4uS",
      "status": "inactive",
      "createdAt": "2026-06-07T10:00:01.000Z",
      "updatedAt": "2026-06-07T10:00:01.000Z"
    }
  ],
  "createdCount": 1,
  "skippedEmails": ["james.carter@example.com"],
  "skippedPhones": [],
  "skippedCount": 1
}

{
  "statusCode": 409,
  "message": "All users already exist or conflict (emails: james.carter@example.com)"
}

{
  "statusCode": 400,
  "message": "Users array is empty"
}

Introduction

Tenant

Environments

Customers

Accounts

KYC

Document reviews

Source of funds

Files

Webhooks

Sync

Sanctions

Add customers in bulk

Sync behavior per entry

Query parameters

Body

Returns

Error codes

​Sync behavior per entry

​Query parameters

​Body

​Returns

​Error codes

Sync behavior per entry

Query parameters

Body

Returns

Error codes