Customers

Create a customer

Changed on Nov 3, 2026

Creates a customer under the authenticated partner tenant. Returns 201 Created for a new customer, or 200 OK when a customer with the same email already exists under your own tenant and is returned instead of duplicated (created: false). An email belonging to any other principal — another tenant's customer, a legacy customer with no tenant, or a non-customer such as a dashboard user — is rejected with 409 E_EMAIL_IN_USE and nothing about that record is returned. Idempotent on the Idempotency-Key header: replaying the same key returns the original result — the same response and status as the first call — never a duplicate. If a create fails before it commits, the key is released; fix the request and retry with the same key.

post/v1/partner/customers

Request

Base URL
https://api.test.doola.com
URL
https://api.test.doola.com/v1/partner/customers
Auth
API key in header Authorization

Headers

Idempotency-Keystring required

Unique key that makes the create safe to retry. Reuse the same value to retry; if the create fails before committing, the key is released, so retry with the same value.

Request body

emailstring required

Customer email address.

firstNamestring required

Customer legal first name.

lastNamestring required

Customer legal last name.

countryOfResidencestring required

ISO 3166-1 alpha-3 country of residence (e.g. USA).

phoneNumberstring

Customer phone number in E.164 format. Optional.

Example request

{
  "email": "founder@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "countryOfResidence": "USA",
  "phoneNumber": "+12125550100"
}

Response

doolaCustomerIdstring

doola customer ID (KSUID).

externalCustomerIdstring nullable

Your own user id, as sent as externalCustomerId when minting an SDK customer session. Null when never sent.

emailstring

Customer email address.

firstNamestring

lastNamestring

countryOfResidencestring

ISO 3166-1 alpha-3 country of residence (e.g. USA).

phoneNumberstring

source'MCP' | 'PARTNER_API' | 'PARTNER_SDK' | 'WHOP_APP' | 'DOOLA_DASHBOARDS'

How the customer was created.

createdboolean

True if this request created the customer; false if it already existed.

Example response

{
  "externalCustomerId": "usr_8f21c",
  "email": "founder@example.com",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "countryOfResidence": "USA",
  "phoneNumber": "+12125550100",
  "companies": [
    {
      "name": "Acme Labs LLC",
      "entityType": "LLC",
      "state": "DE"
    }
  ]
}

Changes

Nov 3, 2026f607744a8927 Revision changes
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the request property's minLength was increased from 0 to 1
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status
- info
  added the optional property to the response with the status

Operation history