POST
/
v1
/
tenants
/
add-user
curl https://v2.app-dev.zquence.com/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"
  }'

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

ScenarioResult
New email + new/no phoneCustomer 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 phone409 Conflict — email already exists with a different phone number.
Existing email, no phone sent this callCustomer synced — treated as a match on email alone, not a phone conflict. 200 OK.
Existing phone + different email409 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

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

​
Body

​
name
string
required
Full display name of the customer.
​
email
string
required
Valid RFC 5322 email address. Stored lowercase. Used as the primary deduplication key alongside phone.
​
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.
​
customerId
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

​
id
string
Customer’s MongoDB ObjectId.
​
name
string
Display name.
​
email
string
Normalized lowercase email address.
​
phone
string
Normalized E.164 phone number.
​
tenantId
string
Owning tenant identifier.
​
environmentId
string | null
Primary environment this customer belongs to.
​
customerId
string | null
Your system’s customer identifier, if provided.
​
status
string
"inactive" on first creation. Advances to "active" once the customer accepts a Zquence account invitation.
​
createdAt
string
ISO 8601 UTC creation timestamp.
​
updatedAt
string
ISO 8601 UTC last-updated timestamp.

​
Error codes

StatusMeaning
400Missing required field (name or email), invalid phone format (if phone was sent), or tenantId not resolvable.
401Missing or invalid API key pair.
409Email exists with a different phone, or phone exists with a different email.
curl https://v2.app-dev.zquence.com/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"
  }'

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

​
Webhook events

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