Contactos
Las personas que han contactado con tu cuenta: listar, buscar, añadir y cambiar contactos.
Los endpoints de contactos devuelven las personas que han contactado con tu cuenta, con su teléfono, email, nombre, idioma y etiquetas, y te permiten añadir y cambiar contactos. Para leer hace falta contacts:read; para añadir y cambiar, contacts:write.
| Endpoint | Ruta | Permiso |
|---|---|---|
| Listar contactos | GET /v1/contacts |
contacts:read |
| Un contacto | GET /v1/contacts/{contact_id} |
contacts:read |
| Añadir un contacto | POST /v1/contacts |
contacts:write |
| Cambiar un contacto | PATCH /v1/contacts/{contact_id} |
contacts:write |
Los contactos son de todo el cliente: una clave limitada a algunos locales recibe 403 insufficient_scope. En los ejemplos, $BASE es https://api.bookline.ai/v1 y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.
Listar contactos
Sección titulada «Listar contactos»GET /v1/contacts devuelve tus contactos, paginados y ordenados por id.
| Parámetro | Tipo | Por defecto | Reglas |
|---|---|---|---|
search |
texto | ninguno | De 1 a 100 caracteres; solo los contactos cuyo nombre completo, email o teléfono lo contienen (sin distinguir mayúsculas) |
tags |
texto, repetible | ninguno | 20 como máximo; solo los contactos que tienen al menos una de estas etiquetas |
limit |
de 1 a 100 | 50 | Contactos por página |
cursor |
texto | ninguno | meta.next_cursor de la página anterior, con los mismos filtros y el mismo limit |
customer_id |
UUID | el cliente de la clave | Consulta qué lee cada clave |
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 }}| Campo | Qué es |
|---|---|
id |
El identificador del contacto |
phone |
Teléfono en E.164; null si solo se conoce otro canal |
given_name, family_name |
Nombre y apellidos |
email |
Dirección de email, en minúsculas |
preferred_language |
El idioma que prefiere el contacto: SPANISH, CATALAN, ENGLISH…; pueden aparecer otros |
tags |
Las etiquetas que le has puesto |
created_at, updated_at |
Cuándo se registró el contacto y cuándo cambió por última vez |
Un contacto
Sección titulada «Un contacto»GET /v1/contacts/{contact_id} devuelve los mismos campos, con una cabecera ETag: la versión que tienes que enviar como If-Match al cambiarlo. Un contacto que no es de tu cliente es 404 not_found.
Añadir un contacto
Sección titulada «Añadir un contacto»POST /v1/contacts añade un contacto. Necesita una cabecera Idempotency-Key (consulta Escribir datos) y, como mínimo, un phone o un email.
| Campo | Reglas |
|---|---|
phone |
Un número válido en E.164: +, prefijo del país y número, p. ej. +34600111222. Se guarda normalizado. Un número nacional sin prefijo del país se rechaza |
email |
Una dirección de email, de hasta 320 caracteres; se guarda en minúsculas |
given_name, family_name |
Hasta 200 caracteres cada uno |
preferred_language |
Un idioma conocido, p. ej. SPANISH, CATALAN, ENGLISH |
tags |
Hasta 20 etiquetas de hasta 100 caracteres |
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"]}'La respuesta es 201 con el contacto tal como queda guardado y su ETag. El teléfono y el email son únicos por cliente: si ya los tiene otro contacto, la respuesta es 409 conflict (“Another contact of the customer already has this phone or email.”).
Cambiar un contacto
Sección titulada «Cambiar un contacto»PATCH /v1/contacts/{contact_id} cambia los campos que envías, con las mismas reglas de arriba. Envía el ETag del contacto como If-Match.
nullquita un campo. Para quitar todas las etiquetas, envía"tags": [];tagssustituye la lista guardada.- Un contacto necesita un teléfono o un email: quitar el último da 422
validation_failed. - Un teléfono o un email que ya tiene otro contacto da 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"]}'La respuesta a un alta o a un cambio es el propio contacto, así que son datos personales: cuenta en el límite de 30 por minuto y queda registrada como una lectura.
Reglas de los datos
Sección titulada «Reglas de los datos»- Solo los campos de esta página. El vínculo del contacto con un usuario del portal, sus conexiones externas y sus ids de WhatsApp e Instagram no forman parte de la API, y no se pueden escribir.
- Paginación. Los contactos añadidos mientras paginas pueden quedar fuera de ese listado, nunca repetirse. Para cuando
next_cursorseanull.
Relacionado
Sección titulada «Relacionado»- Reservas y Chats: lo que han reservado y escrito tus contactos.
- Escribir datos: versiones, reintentos y el límite de escritura.
