Sync users

Every user who goes through KYC or signs an escrow must first exist as a Zquence user. Most integrations push users in two flows:

Live sync - when a user signs up in your app, call add-user to mirror them.
Nightly reconciliation - a batch job runs add-user-bulk to catch anything the live sync missed.

Live sync - single 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" \
  -H "Idempotency-Key: user-sync-$CRM_ID" \
  -d '{
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "phone": "+14155552671"
  }'

const res = await fetch("https://api.zquence.ai/v1/tenants/add-user", {
  method: "POST",
  headers: {
    "x-api-key":       process.env.ZQUENCE_PUBLIC_KEY!,
    "x-api-secret":    process.env.ZQUENCE_SECRET_KEY!,
    "Content-Type":    "application/json",
    "Idempotency-Key": `user-sync-${crmId}`,
  },
  body: JSON.stringify({ name: "Ada Lovelace", email: "ada@example.com", phone: "+14155552671" }),
});
const user = await res.json();

user = requests.post(
    "https://api.zquence.ai/v1/tenants/add-user",
    headers={
        "x-api-key":       os.environ["ZQUENCE_PUBLIC_KEY"],
        "x-api-secret":    os.environ["ZQUENCE_SECRET_KEY"],
        "Idempotency-Key": f"user-sync-{crm_id}",
    },
    json={"name": "Ada Lovelace", "email": "ada@example.com", "phone": "+14155552671"},
).json()

Use your internal user ID as the idempotency key suffix. Retries are then safe: if the sync job restarts, we’ll return the existing user instead of erroring.

Bulk sync - up to 10,000 users

For CRM snapshots, onboarding migrations, or reconciliation jobs, use the bulk endpoint.

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": "Alice", "email": "alice@example.com", "phone": "+14155550111" },
    { "name": "Bob",   "email": "bob@example.com",   "phone": "+14155550112" }
  ]'

const res = await fetch("https://api.zquence.ai/v1/tenants/add-user-bulk", {
  method: "POST",
  headers: {
    "x-api-key":    process.env.ZQUENCE_PUBLIC_KEY!,
    "x-api-secret": process.env.ZQUENCE_SECRET_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify([
    { name: "Alice", email: "alice@example.com", phone: "+14155550111" },
    { name: "Bob",   email: "bob@example.com",   phone: "+14155550112" },
  ]),
});
const result = await res.json();

console.log(result.created, "created,", result.skipped, "skipped");

Response:

{
  "created": 1842,
  "skipped": 158,
  "failed": [
    { "index": 203, "email": "invalid", "error": "email_invalid" }
  ]
}

skipped entries are users whose email already exists for this tenant - this is a no-op success. Inspect failed to see which rows couldn’t be ingested.

Nightly CRM sync pattern

Export delta

Grab users created or updated in the last 24 hours from your CRM.

De-duplicate by email

Guarantees the bulk endpoint’s skipped count is meaningful.

Chunk to 1,000

We accept up to 10,000 per call - 1,000 gives smaller retry units.

Retry on 429

Honor Retry-After. Use the rate-limit helper.

Log failed[] to your ops channel

So someone can fix invalid emails before the next run.

Event on success

Each added user fires a tenant.users.invite webhook. Subscribe if you want to drive downstream automation (welcome email, Slack alert, analytics event).

Core workflows

Webhooks

Live sync - single user

Bulk sync - up to 10,000 users

Nightly CRM sync pattern

Event on success

​Live sync - single user

​Bulk sync - up to 10,000 users

​Nightly CRM sync pattern

​Event on success

Live sync - single user

Bulk sync - up to 10,000 users

Nightly CRM sync pattern

Event on success