POST
/
v1
/
tenants
/
add-user
curl https://api.zquenceeee.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. Idempotent on email + phone: if a user with the same email and 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 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 phone + different email409 Conflict — phone already exists with a different email.

​
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
required
Phone number. 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, email, or phone), invalid phone format, 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://api.zquenceeee.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.