Skip to main content
PATCH
Update a customer in the organization's directory
Changes a customer’s name, customerType (org or user), status (active, inactive or archived), primaryEmail, primaryPhone, website, externalIds or metadata. Send id plus at least one field; omitted fields are unchanged. The body is strict: an unknown field, an empty string, or id alone is 400 bad_request. status: "active" restores an archived customer, and an organization customer that is active afterwards keeps its organization home. An unknown or malformed id is 404 resource_missing. The credential needs both the customers:read and customers:manage scopes, and customers:read and customers:manage granted at the deployment root; otherwise 403 permission_denied names the missing permission. The customer row is shared: every application linked to it, and the Console, see the change. Success is 200 with the post-write {customer}. A same-key retry within 24 hours returns the recorded result while the caller still holds both permissions at the deployment root; otherwise 409 idempotency_result_unavailable. Reconcile an unknown outcome with Get customer.

Authorizations

Authorization
string
header
required

An External App: the JWT it obtains from POST /oauth/token with OAuth2 client_credentials. Pass as Authorization: Bearer <jwt>. An app's static companion key also authenticates as the app, but is deprecated and is not protected by Idempotency-Key.

Headers

Idempotency-Key
string

1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.

Required string length: 1 - 255

Path Parameters

customerId
string
required

The customer id, as the directory reads return it.

Minimum string length: 1

Body

application/json
name
string
Minimum string length: 1
customerType
enum<string>

org for businesses and organizations, user for individuals.

Available options:
org,
user
status
enum<string>

archived archives the customer; active restores it.

Available options:
active,
inactive,
archived
primaryEmail
string
Minimum string length: 1
primaryPhone
string
Minimum string length: 1
website
string
Minimum string length: 1
externalIds
any

CRM dedup anchors, e.g. {hubspot: "123"}.

metadata
any

Response

The updated customer

data
object
required
meta
object
required