Create an account

POST

accounts

curl -i https://v2.app-dev.zquence.com/v1/accounts \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Idempotency-Key: crm-case-10482-open" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "permanent",
    "title": "Maria Alvarez onboarding",
    "externalReference": "crm-case-10482",
    "participants": [
      { "role": "customer", "userId": "6a25cdac36bc6230704b5b59" }
    ]
  }'

{
  "id": "6a25cdcc36bc6230704b5bce",
  "externalReference": "crm-case-10482",
  "accountType": "permanent",
  "title": "Maria Alvarez onboarding",
  "status": "invited",
  "participants": [
    { "role": "customer", "userId": "6a25cdac36bc6230704b5b59", "accepted": false }
  ],
  "createdAt": "2026-09-15T10:00:00.000Z",
  "updatedAt": "2026-09-15T10:00:00.000Z"
}

Creates an account for one or two existing customers and sends them their invitation emails. Use it to open accounts from a CRM, case-management tool, or onboarding backend without going through the Zquence console. The API key decides where the account is created. The tenant and the environment (sandbox or live) both come from the key, so there is no tenant or environment field in the body.

Requires an API key with the accounts.write scope that is bound to an environment. API-key authentication only. Console sessions cannot call this endpoint.

Before you call it

Create the customers

Every participant must already exist as a customer under your tenant. Create them with Add a customer and keep the returned id. That value is the userId you send here.

Pick the account type

Use the account-type code configured for your tenant, for example permanent or real_estate. The account type decides how many participants the account takes (see Participants).

Generate an idempotency key

Build a key from your own record, for example crm-case-10482-open, and send the same key on every retry of that create. See Retries and idempotency.

Headers

x-api-key

string

required

Public key of an environment-bound API key with the accounts.write scope.

x-api-secret

string

required

Secret for the same key.

Idempotency-Key

string

required

Your unique key for this create operation. 8–255 visible ASCII characters, no spaces (for example a UUID, or crm-case-10482-open). Leading and trailing whitespace is trimmed.

Content-Type

string

required

application/json

Body

The body is strict. Any field not listed below, at the top level or inside a participant, is rejected with 400 unknown_request_fields. Nothing is silently ignored.

accountType

string

required

Account-type code configured for your tenant. Up to 64 characters. Must start with a letter or number and may contain only letters, numbers, _, and -. Matching is case-insensitive, and the value is stored in lowercase.

title

string

required

Human-readable account title shown in the console and in invitation emails. 1–160 characters after trimming.

externalReference

string

Your stable identifier for this account, such as a CRM case ID. 1–128 characters after trimming. Must be unique within the environment. A second account with the same value is rejected with 409 external_reference_exists. Returned on every read so you can match Zquence accounts back to your records.

participants

object[]

required

One or two participants. See Participants for the combinations that are allowed.

Show participant properties

role

string

required

customer, buyer, or seller.

userId

string

required

The customer id returned by Add a customer. Up to 128 characters. The same userId cannot appear twice.

Participants

Send exactly one of these two shapes. Anything else returns 400 invalid_participants.

Shape	`participants`	Use for
Single customer	`[{ "role": "customer", "userId": "…" }]`	Account types with one customer, such as `permanent` or `construction`.
Buyer and seller	`[{ "role": "buyer", "userId": "…" }, { "role": "seller", "userId": "…" }]`	Two-party account types, such as `real_estate`. The two `userId` values must be different customers.

The shape must also match how the account type is configured. Sending one customer for a buyer-and-seller account type, or a buyer and seller for a single-customer type, returns 400. real_estate always needs a buyer and a seller.

What happens when the account is created

The account is created in the key’s environment with status invited.
Each participant gets an invitation email. A participant who already has a password gets a login link instead of an invite link.
Zquence sends an account.created webhook, then one account.invited webhook per participant.

An email that fails to send does not fail the request. The account is still created.

Retries and idempotency

Send the same Idempotency-Key and the same body to retry safely. You never get a second account.

You send	Result
A new key	Account created. `201 Created`.
A key you already used, with the same body	No new account and no new emails or webhooks. The existing account is returned with `201 Created`, showing its current state.
A key you already used, with a different body	`409 idempotency_key_reused`. Nothing is created.
A new key with an `externalReference` that already exists	`409 external_reference_exists`. Nothing is created.

Keys are scoped to the API key and environment that used them, and they don’t expire. Two bodies count as the same when they match after trimming, lowercasing accountType, and ignoring participant order.

Retry on network errors, timeouts, 429, and 5xx with the same key. Don’t retry 400, 401, 403, or 409. Fix the request first. A request that failed validation stores nothing, so you can reuse its key after fixing the body.

Returns

201 Created, with a Location header pointing at the account, for example Location: /v1/accounts/6a25cdcc36bc6230704b5bce. The body contains no invitation tokens.

string

Account ID. Use it with Retrieve an account.

externalReference

string

Your reference. Omitted when you didn’t send one.

accountType

string

Account-type code, in lowercase.

title

string

Account title.

status

string

invited on creation. Later values: pending, accepted, completed, cancelled.

participants

object[]

Show participant properties

role

string

customer for single-customer accounts, or buyer and seller for two-party accounts.

userId

string

Customer ID.

accepted

boolean

Whether this participant has accepted the invitation. false on creation.

createdAt

string

ISO 8601 UTC creation timestamp.

updatedAt

string

ISO 8601 UTC last-updated timestamp.

Error codes

Every error uses the standard envelope: statusCode, message, path, correlationId, timestamp, and a code when one applies. Branch on code where present. message text can change.

Status	`code`	Meaning and fix
`400`	`invalid_idempotency_key`	`Idempotency-Key` is missing, shorter than 8 or longer than 255 characters, or contains spaces or non-ASCII characters.
`400`	`unknown_request_fields`	The body has fields this endpoint doesn’t accept. `fields` lists them, for example `["amount", "participants[0].email"]`.
`400`	`invalid_participants`	`participants` isn’t one `customer` or one `buyer` plus one `seller`.
`400`	—	Field validation failed. `message` is an array of problems, such as a missing `title`, a malformed `accountType`, or a duplicate `userId`.
`400`	—	The account type isn’t allowed for your tenant, the participant shape doesn’t match the account type, or a participant belongs to another tenant.
`401`	`key_missing` / `key_invalid` / `key_revoked`	`x-api-key` / `x-api-secret` missing, wrong, or revoked.
`401`	`api_key_required`	The request was authenticated without an API key. This endpoint accepts API keys only.
`403`	`key_forbidden`	The key lacks the `accounts.write` scope.
`403`	`environment_binding_required`	The key isn’t bound to an environment. Create a sandbox or live key and use that instead.
`404`	—	A `userId` doesn’t match a customer (`Buyer not found for id …` / `Seller not found for id …`).
`409`	`idempotency_key_reused`	The key was already used with a different body. Use a new key for a different account.
`409`	`external_reference_exists`	Another account in this environment already has this `externalReference`.
`409`	—	The tenant has reached its monthly account limit.
`429`	—	Rate limit exceeded. Back off and retry with the same key.

curl -i https://v2.app-dev.zquence.com/v1/accounts \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Idempotency-Key: crm-case-10482-open" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "permanent",
    "title": "Maria Alvarez onboarding",
    "externalReference": "crm-case-10482",
    "participants": [
      { "role": "customer", "userId": "6a25cdac36bc6230704b5b59" }
    ]
  }'

{
  "id": "6a25cdcc36bc6230704b5bce",
  "externalReference": "crm-case-10482",
  "accountType": "permanent",
  "title": "Maria Alvarez onboarding",
  "status": "invited",
  "participants": [
    { "role": "customer", "userId": "6a25cdac36bc6230704b5b59", "accepted": false }
  ],
  "createdAt": "2026-09-15T10:00:00.000Z",
  "updatedAt": "2026-09-15T10:00:00.000Z"
}

Retrieve an accountFetch a single account by its ID.

curl -i https://v2.app-dev.zquence.com/v1/accounts \
  -H "x-api-key: $ZQUENCE_PUBLIC_KEY" \
  -H "x-api-secret: $ZQUENCE_SECRET_KEY" \
  -H "Idempotency-Key: crm-case-10482-open" \
  -H "Content-Type: application/json" \
  -d '{
    "accountType": "permanent",
    "title": "Maria Alvarez onboarding",
    "externalReference": "crm-case-10482",
    "participants": [
      { "role": "customer", "userId": "6a25cdac36bc6230704b5b59" }
    ]
  }'

{
  "id": "6a25cdcc36bc6230704b5bce",
  "externalReference": "crm-case-10482",
  "accountType": "permanent",
  "title": "Maria Alvarez onboarding",
  "status": "invited",
  "participants": [
    { "role": "customer", "userId": "6a25cdac36bc6230704b5b59", "accepted": false }
  ],
  "createdAt": "2026-09-15T10:00:00.000Z",
  "updatedAt": "2026-09-15T10:00:00.000Z"
}

​Before you call it

​Headers

​Body

​Participants

​What happens when the account is created

​Retries and idempotency

​Returns

​Error codes

Before you call it

Headers

Body

Participants

What happens when the account is created

Retries and idempotency

Returns

Error codes