Create a customer, or update / skip the one it duplicates

post

https://apis.kentro.live/channel/v1/customers

Duplicates are looked up in the sales channel by id, externalId, email, then phone digits. onDuplicate (default 'update') decides: 201 created, 200 updated or skipped, 409 duplicate; an inactive match is 422 inactive_customer. An update that changes nothing writes nothing and answers 200 unchanged. Unknown fields are refused (400).

Scope: customers:write, channel:write or admin.

Idempotency: send Idempotency-Key; a retry with the same key replays the first answer.

Rate limit: write class, 1,200 requests per minute per tenant by default (read class 6,000). Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; a refusal is 429 rate_limited with Retry-After.

Body Params

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or a legacy 24-hex id.

externalId

string

length between 1 and 255

The integration's own id for the document, unique within its channel.

channelId

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

Sales channel id: a uuid, or a legacy 24-hex id.

name

string

length ≤ 1000

Defaults to firstName + lastName, then to the email local part.

firstName

string

length ≤ 255

lastName

string

length ≤ 255

string

length ≤ 255

phone

string

length ≤ 255

isActive

boolean

Default true on create.

taxExempt

boolean

Default false on create.

taxExemptions

array of strings

length ≤ 100

Tax exemption codes; replaces the whole list, [] clears it.

taxExemptions

hasCreditLimit

boolean

Default false on create.

creditLimit

length ≤ 24

^[0-9]{1,14}(\.[0-9]{1,8})?$

A non-negative decimal amount in currency units ("12.50"); numbers are accepted.

priceListId

string

^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|[0-9a-fA-F]{24})$

A uuid, or a legacy 24-hex id.

userGroupIds

array of strings

length ≤ 100

User groups of the tenant; replaces the whole list, [] clears it.

userGroupIds

signupApplicationStatus

enum

expiresAt

date-time

When the customer was retired (the legacy TTL tombstone); readers treat any value as gone, not as a future end date.

password

string

length ≤ 1000

Plain password, hashed with bcrypt (cost 10). 8 characters to 72 bytes after trimming.

passwordHash

string

length between 1 and 255

A pre-hashed password stored exactly as sent (no hashing, no format check): a bcrypt hash verifies at login, anything else fails every login until a password is set. Exclusive with password.

addresses

array of objects

length ≤ 50

On an update, replaces the whole set; [] clears it.

addresses

metadata

object

Keys 1 to 100 characters, values up to 1000.

externalCreatedAt

date-time

ISO-8601, UTC.

onDuplicate

enum

What a POST does when the document already exists. Default 'update' (D7).

Headers

Idempotency-Key

string

length between 7 and 50

Any string of 7 to 50 characters that identifies this request (an order number, a webhook id). A retry with the same key and the same body answers the first result with Idempotent-Replayed: true; the same key with a different body is 422 idempotency_key_reused; a concurrent request with the same key is 409 in_progress with Retry-After. Recommended on every write.

Responses

Language

Credentials

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200Default Response

201Default Response

400Default Response

404Default Response

409Default Response

422Default Response