Customers

Create a customer

View as Markdown
Enrolls a customer in your loyalty program. The phone number is the customer identity within your company: any parseable format is accepted and canonicalized to E.164, and a duplicate phone is rejected with 409 `API_CUSTOMERS.ALREADY_EXISTS` — this is a deliberate create that never silently returns an existing customer. Optionally pass `externalId` to link the customer to your own system (unique per company). Newly created customers receive their enrollment email automatically.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Headers

Idempotency-KeystringOptional

Optional but recommended. When present, a retry with the same key and payload replays the stored response for 24h instead of re-executing; the same key with a different payload is rejected with 409 IDEMPOTENCY.PAYLOAD_MISMATCH.

Request

This endpoint expects an object.
firstNamestringRequired
Customer first name.
lastNamestringRequired
Customer last name.
emailstringRequired

Contact email. Not an identity key — two customers may share an email.

phonestringRequired

Phone number in any parseable format; stored canonicalized to E.164. This is THE customer identity within your company — creating with an already-registered phone returns 409.

externalIdstringOptional

Your own identifier for this customer (CRM id, member number, …). Unique within your company; a conflicting value returns 409.

birthdaystringOptional

Birthday as an ISO date (YYYY-MM-DD).

genderenumOptional
Customer gender.
addressstringOptional

Postal address, free-form.

Response

The customer as stored (phone canonicalized to E.164).

idstring

Perkss customer id (UUID). Use it for every customer-scoped call.

externalIdstring or null

Your own identifier for this customer — unique per company when set; null when never supplied.

firstNamestring
lastNamestring
emailstring
phonestring

E.164. Phone is the customer identity within your company — inputs in any parseable format are canonicalized to this form.

createdAtstring
ISO 8601 creation timestamp.

Errors

400
Bad Request Error
401
Unauthorized Error
409
Conflict Error
429
Too Many Requests Error
503
Service Unavailable Error