Skip to content

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.

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
Ventana de terminal
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

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.

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
Ventana de terminal
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.”).

PATCH /v1/contacts/{contact_id} changes the fields you send, with the same rules as above. Send the contact’s ETag as If-Match.

  • null removes a field. To remove every tag, send "tags": []; tags replaces 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.
Ventana de terminal
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.

  • 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_cursor is null.