Ir al contenido

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.

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
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 }
}
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

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.

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
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"]}'

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.”).

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.

  • null quita un campo. Para quitar todas las etiquetas, envía "tags": []; tags sustituye 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.
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"]}'

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.

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