Contacts
The people who reached your account: list, search, add and change contacts.
The contacts endpoints return the people who reached your account, with their phone, email, name, language and tags, and let you add and change contacts. Reading needs contacts:read; adding and changing needs contacts:write.
| Endpoint | Route | Scope |
|---|---|---|
| List contacts | GET /v1/contacts |
contacts:read |
| One contact | GET /v1/contacts/{contact_id} |
contacts:read |
| Add a contact | POST /v1/contacts |
contacts:write |
| Change a contact | PATCH /v1/contacts/{contact_id} |
contacts:write |
Contacts belong to the whole customer: a key limited to some venues gets 403 insufficient_scope. In the examples, $BASE is https://api.bookline.ai/v1 and $BOOKLINE_API_KEY is your key, as in the quick start.
List contacts
Section titled “List contacts”GET /v1/contacts returns your contacts, paged, ordered by id.
| Parameter | Type | Default | Rules |
|---|---|---|---|
search |
string | none | 1 to 100 characters; only contacts whose full name, email or phone contains it (case-insensitive) |
tags |
string, repeatable | none | At most 20; only contacts holding at least one of these tags |
limit |
1 to 100 | 50 | Contacts per page |
cursor |
string | none | meta.next_cursor of the previous page, with the same filters and the same limit |
customer_id |
UUID | the key’s customer | See what each key reads |
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/contacts?tags=vip&limit=100"{ "data": [ { "id": "…", "phone": "+34600111222", "given_name": "Ana", "family_name": "García", "email": "ana@example.com", "preferred_language": "SPANISH", "tags": ["vip"], "created_at": "2026-03-02T10:15:00Z", "updated_at": "2026-10-20T16:40:00Z" } ], "meta": { "limit": 100, "next_cursor": null }}| Field | What it is |
|---|---|
id |
The contact’s identifier |
phone |
Phone number in E.164; null when only another channel is known |
given_name, family_name |
First and last name |
email |
Email address, lower-cased |
preferred_language |
The language the contact prefers: SPANISH, CATALAN, ENGLISH…; others may appear |
tags |
The labels you gave the contact |
created_at, updated_at |
When the contact was first recorded and last changed |
One contact
Section titled “One contact”GET /v1/contacts/{contact_id} returns the same fields, with an ETag header: the version to send as If-Match when you change it. A contact that is not your customer’s is 404 not_found.
Add a contact
Section titled “Add a contact”POST /v1/contacts adds a contact. It needs an Idempotency-Key header (see Writing data) and at least a phone or an email.
| Field | Rules |
|---|---|
phone |
A valid number in E.164: +, country code and number, e.g. +34600111222. Stored normalised. A national number without its country code is refused |
email |
An email address, up to 320 characters; stored lower-cased |
given_name, family_name |
Up to 200 characters each |
preferred_language |
A known language, e.g. SPANISH, CATALAN, ENGLISH |
tags |
Up to 20 labels of up to 100 characters |
curl -s -X POST "$BASE/contacts" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d '{"phone": "+34600111222", "given_name": "Ana", "tags": ["vip"]}'The answer is 201 with the contact as stored and its ETag. The phone and the email are unique per customer: one another contact already has is 409 conflict (“Another contact of the customer already has this phone or email.”).
Change a contact
Section titled “Change a contact”PATCH /v1/contacts/{contact_id} changes the fields you send, with the same rules as above. Send the contact’s ETag as If-Match.
nullremoves a field. To remove every tag, send"tags": [];tagsreplaces the stored list.- A contact needs a phone or an email: removing the last one is 422
validation_failed. - A phone or email another contact already has is 409
conflict.
curl -s -X PATCH "$BASE/contacts/<contact_id>" \ -H "apikey: $BOOKLINE_API_KEY" \ -H "Content-Type: application/json" \ -H 'If-Match: "<etag>"' \ -d '{"email": "ana.garcia@example.com", "tags": ["vip", "newsletter"]}'The answer to an add or a change is the contact itself, so it is personal data: it counts in the 30-per-minute limit and is recorded like a read.
Data rules
Section titled “Data rules”- Only the fields on this page. The contact’s link to a portal user, its external connections and its WhatsApp and Instagram ids are not part of the API, and cannot be written.
- Paging. Contacts added while you page may be left out of that listing, never repeated. Stop when
next_cursorisnull.
Related
Section titled “Related”- Bookings and Chats: what your contacts booked and wrote.
- Writing data: versions, retries and the write limit.
