Organization API

Create or link a Customer

Creates or links a Customer for the calling organization. An email matches only a Customer this organization already serves, or one it deleted, which restores them; the email of a merged Customer follows the Customer it was merged into. An email held by a Customer this organization does not serve gets its own record holding only what was sent, and the response reads the same as a new Customer. Requires Idempotency-Key. Required scope: customers:write.

/api/v1/customers

Create or link a Customer. Use an organization API key with customers:write. Check the response envelope and meta.requestId before triggering dependent workflow steps.

Required scopes

customers:writeIdempotency-Key required

Parameters

No path or query parameters.

Request body

objectrequired

Field	Type	Description
firstNamerequired	string	Optional unless marked required.
lastNamerequired	string	Optional unless marked required.
billingEmail	string \| null	Invoice recipient for this organization. Blank or null uses the contact email.
emailrequired	string	Optional unless marked required.
phone	string \| null	Optional unless marked required.
displayName	string \| null	Optional unless marked required.
description	string \| null	Optional unless marked required.
internalNotes	string \| null	Optional unless marked required.
tags	array \| null	Optional unless marked required.
referralSource	string \| null	Optional unless marked required.
ownerId	string \| null	Active or draft same-organization Team Member id. When omitted, the API key default owner for this resource is used. Ownership cannot be changed through generic PATCH endpoints.
customFields	object	Field Values keyed by savedIdentity from GET /api/v1/schema.
externalReferences[]	array<object>	Optional unless marked required.
externalReferences[].externalSystemrequired	string	Optional unless marked required.
externalReferences[].externalObjectrequired	string	Optional unless marked required.
externalReferences[].externalIdrequired	string	Optional unless marked required.
externalReferences[].metadata	object	Optional unless marked required.

createcustomerRequest

{
  "firstName": "Ada",
  "lastName": "Lovelace",
  "email": "ada@example.com",
  "phone": "+15555550123",
  "customFields": {
    "preferredLanguage": "en"
  },
  "externalReferences": [
    {
      "externalSystem": "salesforce",
      "externalObject": "Contact",
      "externalId": "003123"
    }
  ]
}

Responses

201

Customer envelope

#/components/schemas/OrgApiResourceEnvelope

400

Validation, ownership, idempotency, or custom Field error