Find or create a customer

post

https://customer-services.omni.chat/v1/customers/find-or-upsert

Looks up a customer in the following order of precedence:

externalId (when provided)
phone
email (when provided and not found by the previous criteria)

If no match is found, a new customer is created. If a match is found, the fields sent in the request are updated.

The retailerId is resolved only from the authorizer context (do not rely on a retailerId field in the body — it is ignored in favor of the authorizer when present).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Finds or creates a customer by phone number (required). If externalId is provided, the lookup
is performed first by it, then by phone and, optionally, by email.
When the customer already exists, the fields sent are updated. customFields is merged with existing
values. acceptsMarketing is sent as a string; only the literal "true" is persisted as boolean true.

Same payload shape is used for POST /v1/customers (create-only). Do not send retailerId in the JSON body for either endpoint — it comes from the Lambda authorizer.

phone

object

required

string

externalId

string

Customer external identifier in the retailer's system.

name

string

lastName

string

customFields

array of objects

customFields

acceptsMarketing

string

Use a string; only "true" is stored as boolean true in the backend.

birthDate

date

businessAccount

boolean

businessName

string

taxDocumentNumber

string

Customer tax document number (CPF or CNPJ).

address

object

gender

string

enum

Allowed:

Responses

200Customer found or created successfully.

400Bad request

401Unauthorized

403Forbidden

500Internal server error