Skip to navigation

Create a new customer

Creates a new customer for the organization. externalId shares one set of ids with customer unit ids and aliases, unique across the organization and ignoring letter case: an external id that another customer already holds as a unit id or alias, or as its external id in another case, or one another customer’s signals named as a unit id that customer has not created yet, is refused with 409 EXTERNAL_ID_IN_USE. The same id in the same case is 400 DUPLICATE_EXTERNAL_ID, as before.

Authentication

AuthorizationBearer
API Key authentication using Bearer token

Request

Body
namestringRequired>=1 character
legalNamestring or nullOptional
emailstringOptionalformat: "email"
phonestringOptional
websitestringOptional
externalIdstring or nullOptional
billingAddressobjectOptional
creationStateenumOptional
Allowed values:
vatNumberstring or nullOptional
metadatamap from strings to any or nullOptional
defaultCurrencystringOptional

Response

201
idstring

Stable Paid customer display ID. Use this value as the {id} path parameter for customer routes, for example GET /api/v2/customers/cus_abc123/state.

namestring
legalNamestring or null
emailstring
phonestring
websitestring
externalIdstring or null
billingAddressobject
Customer billing address, or null when no address is set.
creationStateenum
Allowed values:
statusenum

Customer status: churned when the customer is marked as churned, active otherwise.

Allowed values:
churnDatedatetime or null
vatNumberstring or null
metadatamap from strings to any or null
defaultCurrencystringformat: "^[A-Z]{3}$"
ISO 4217 currency code, for example USD, EUR, or GBP.
connectionsobject
Linked external system IDs for this customer.
createdAtdatetime
updatedAtdatetime

Errors

400
Bad Request Error
403
Forbidden Error
409
Conflict Error
500
Internal Server Error