Skip to content
/
Create a client

Create a client

Request

Creates a client. name and phone are required. The phone number is deduplicated within the Location: if another (non-deleted) client already owns it, the request fails with 422 phone_taken. That signal is part of clients:write (no clients:read_contact required); it does not reveal the other client's id or contacts. Phone-bearing writes are audited and rate-limited against enumeration. Requires Idempotency-Key.

Contact fields in the response follow the redaction contract: without clients:read_contact they are returned as null and listed in redacted_fields, never as a placeholder string.

Security
OAuth2(Required scopes: clients:write) or ApiKey
Path
location_idintegerrequired

Identifier of the Location. Verified against the credential on every call — a Location the credential cannot access responds with 404.

Bodyapplication/jsonrequired
namestringrequired
phonestringrequired

International format. Deduplicated within the Location (422 phone_taken).

surnamestring
patronymicstring
emailstring
additional_phonestring
birth_datestring, (date)
commentstring
discountnumber

Personal discount, percent.

curl -i -X POST \
  'https://developer.alteg.io/_mock/en/b2b-v3/openapi/locations/{location_id}/clients' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Demo",
    "surname": "Client",
    "phone": "+351210000175",
    "email": "demo.client@example.com",
    "birth_date": "1990-04-12"
  }'

Responses

The created client.

Headers
RateLimit-Remaininginteger, (int32), >= 0

Requests left in the most constrained policy window that applies to this request.

RateLimit-Resetinteger, (int32), >= 0

On 429, seconds until the most constrained policy frees up; it equals Retry-After there. On a successful response it reports the length of that policy's window rather than the time left in the current one, so treat it as the window size, not as a countdown — the counter to pace against is RateLimit-Remaining.

RateLimit-Policystring

Most constrained policy applied to the request, as <limit>;w=<window in seconds>.

Example:"10;w=60"
Locationstring

URL of the created resource.

X-Request-Idstring

Request identifier for support and log correlation.

Bodyapplication/json
idintegerread-onlyrequired
objectstringread-onlyrequired
Value:"client"
namestringrequired
phonestring or nullrequired

International phone number. null when absent or withheld — see redacted_fields.

surnamestring or null
patronymicstring or null
display_namestringread-only
additional_phonestring or null

Additional phone number. null when absent or withheld — see redacted_fields.

emailstring or null

Email address. null when absent or withheld — see redacted_fields.

birth_datestring or null, (date)
commentstring or null

Private note about the client; requires comment access.

discountnumber or null

Personal discount, percent.

visits_countintegerread-only
first_visit_atstring or null, (date-time)read-only

Location-local offset.

last_visit_atstring or null, (date-time)read-only

Location-local offset.

currencystringread-only

ISO 4217, server-controlled by the Location.

created_atstring, (date-time)read-only

UTC.

updated_atstring, (date-time)read-only

UTC.

sold_amount_minorintegerread-only

Lifetime paid total, integer minor units of the Location currency.

redacted_fieldsArray of stringsread-only

Names of fields withheld by the PII policy for this object, for example ["phone", "email"]. A withheld contact is always returned as null — never as a masked or empty string, so an integration cannot write a mask back. An empty array means nothing was withheld and a null value simply means no value is stored.

Response
{
  "id": 789,
  "object": "client",
  "name": "Demo",
  "surname": "Client",
  "patronymic": null,
  "display_name": "Demo Client",
  "phone": "+351210000175",
  "additional_phone": null,
  "email": "demo.client@example.com",
  "birth_date": "1990-04-12",
  "comment": null,
  "discount": 5,
  "visits_count": 12,
  "first_visit_at": "2025-11-02T10:00:00+00:00",
  "last_visit_at": "2026-07-09T11:30:00+01:00",
  "currency": "EUR",
  "created_at": "2025-11-02T09:57:15Z",
  "updated_at": "2026-07-09T09:57:15Z",
  "sold_amount_minor": 1250000
}