API
Contactos
Consulta y actualiza información de contactos
# Contactos > Consulta y actualiza información de contactos - Página: https://tbit.app/es/docs/api/contacts - URL base: `https://rest-api.tbit.app/v1` - Autenticación: encabezado `X-API-Key` con tu clave en cada solicitud (los ejemplos la leen de la variable de entorno `TBIT_API_KEY`) ## Descripción general Los contactos representan las personas que interactúan con tu agente a través de canales como WhatsApp, Instagram y email. Cada contacto tiene un perfil con nombre, identificadores de canal y metadatos opcionales. ## Endpoints | Método | Ruta | Descripción | | --- | --- | --- | | `GET` | `/v1/contacts` | Listar contactos | | `GET` | `/v1/contacts/:id` | Ver el detalle de un contacto | | `POST` | `/v1/contacts` | Crear un contacto | | `PATCH` | `/v1/contacts/:id` | Actualizar un contacto | | `PUT` | `/v1/contacts` | Crear o actualizar por teléfono o correo (upsert) | | `GET` | `/v1/contacts?phone=\|email=` | Buscar contactos por teléfono o correo | | `PATCH` | `/v1/contacts/:id/attributes` | Guardar atributos del contacto | | `PUT` | `/v1/contacts/:id/stage` | Poner al contacto en una etapa de un embudo | | `POST` | `/v1/contacts/:id/events` | Agregar un evento a su línea de tiempo | ## Parámetros de consulta El endpoint de listado soporta los siguientes parámetros de consulta: | Parámetro | Tipo | Descripción | | --- | --- | --- | | `limit` | `number` | Resultados por página (predeterminado: 20, máximo: 100) | | `offset` | `number` | Número de resultados a omitir (predeterminado: 0) | ## Listar Contactos `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Obtener Detalle de Contacto `GET /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Actualizar Contacto `PATCH /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "profile_name": "Jane Doe", "email": "[email protected]", "notes": "Preferred language: English" }' ``` ## Crear Contacto Los custom_attributes se validan con las mismas reglas de «Guardar atributos» antes de escribir nada. Si un valor no sirve responde 400 VALIDATION_ERROR con el motivo de cada clave (Invalid custom_attributes: «clave»: «motivo») y no se guarda ni el contacto ni sus atributos. Un atributo que no existe se crea con el tipo deducido del valor. `POST /v1/contacts` ```bash curl -X POST "https://rest-api.tbit.app/v1/contacts" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "channel_id": "573009876543", "channel_type": "whatsapp", "profile_name": "Jane Doe", "custom_attributes": { "city": "Bogota", "plan": "premium" } }' ``` ## Crear o actualizar por teléfono o correo Busca el contacto de tu agente por su WhatsApp (E.164, con o sin «+») y, si no aparece, por su correo. Si no existe, lo crea; si existe, le agrega el canal que le falte. Nunca pisa un nombre que el contacto ya tenga. Responde 201 cuando lo crea y 200 cuando lo encuentra. Si el teléfono y el correo son de dos contactos distintos responde 409 CONTACT_CONFLICT con los dos ids y no escribe nada. Los atributos que mandes se validan antes de tocar el contacto (ver «Guardar atributos»). `PUT /v1/contacts` ```bash curl -X PUT "https://rest-api.tbit.app/v1/contacts" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone": "+573001234567", "email": "[email protected]", "first_name": "Ana", "last_name": "Pérez", "attributes": { "plan": "premium" } }' ``` Respuesta: ```json { "data": { "created": true, "matched_by": null, "contact": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "first_name": "Ana", "last_name": "Pérez", "profile_name": "Ana Pérez", "phone": "573001234567", "email": "[email protected]", "channels": [ { "channel_type": "whatsapp", "channel_id": "573001234567" }, { "channel_type": "email", "channel_id": "[email protected]" } ], "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "stages": [ { "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "funnel_name": "Clientes", "stage": "prueba", "stage_name": "En prueba" } ], "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-08T15:00:00.000Z" } } } ``` ## Buscar por teléfono o correo Devuelve hasta 10 contactos de tu agente que tengan ese WhatsApp (en cualquiera de sus grafías) o ese correo, con sus atributos y las etapas de embudo en las que están. Sin phone ni email, el endpoint sigue siendo el listado paginado de siempre. `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \ -H "X-API-Key: $TBIT_API_KEY" ``` Respuesta: ```json { "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "first_name": "Ana", "last_name": "Pérez", "profile_name": "Ana Pérez", "phone": "573001234567", "email": "[email protected]", "channels": [ { "channel_type": "whatsapp", "channel_id": "573001234567" }, { "channel_type": "email", "channel_id": "[email protected]" } ], "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "stages": [ { "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "funnel_name": "Clientes", "stage": "prueba", "stage_name": "En prueba" } ], "created_at": "2026-10-01T12:00:00.000Z", "updated_at": "2026-10-08T15:00:00.000Z" } ] } ``` ## Guardar atributos Las claves son el NOMBRE del atributo, tal como se ve en «Datos del contacto» (sin importar mayúsculas ni tildes). Todo o nada: si una clave no existe responde 422 UNKNOWN_ATTRIBUTES con la lista en details.missing, y si un valor no cabe en su tipo (una opción que no está en la lista, un número que no es número, una fecha que no se puede leer) responde 422 INVALID_VALUE; en los dos casos no se guarda ninguno. Fechas: se aceptan cuatro formas: fecha completa (2026-11-14), año y mes (2026-11), día y mes sin año (--11-14) o solo el mes (--11). Una fecha con hora (2026-11-14T15:00:00Z) se guarda como su día, y la API la devuelve siempre sin hora (2026-11-14). Listas de objetos, como «Fechas especiales»: cada ítem se valida contra su esquema. Los campos de fecha usan esas cuatro formas, los obligatorios no pueden ir vacíos y los de opciones deben ser una de la lista (sin importar mayúsculas ni tildes; se guarda escrita como la opción). Con create_missing: true se crean los que falten (el tipo se deduce del valor). null borra el valor. Cada valor nuevo cuenta como «atributo llenado»: un embudo con una regla por ese atributo mueve la tarjeta igual que cuando lo llena la IA. `PATCH /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes` ```bash curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "create_missing": false }' ``` Respuesta: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "updated": [ "plan", "ciudad" ], "created_attributes": [] } } ``` ## Poner en una etapa de un embudo Indica el embudo por funnel_id o por su nombre (funnel) y la etapa por su slug. Si el contacto no está en ese embudo lo agrega; si está en otra etapa lo mueve; si ya está ahí no hace nada (changed: false). Corren las acciones de entrada de la etapa y queda en el historial del contacto. Por defecto no suena la campana del equipo: manda notify: true si quieres el aviso. Errores: 404 FUNNEL_NOT_FOUND y 422 UNKNOWN_STAGE (con la lista de etapas). `PUT /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage` ```bash curl -X PUT "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "funnel": "Clientes", "stage": "prueba" }' ``` Respuesta: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "stage": "prueba", "previous_stage": "registrado", "changed": true } } ``` ## Agregar un evento a la línea de tiempo Deja un hito en la ficha del contacto, con su fecha (occurred_at, por defecto ahora; no puede ser futura). Con idempotency_key el mismo evento no se duplica: repetir la llamada responde 200 con duplicate: true y el evento original. data acepta hasta 20 claves con texto, número o booleano. Los contactos de otro agente responden 404, igual que uno que no existe. `POST /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events` ```bash curl -X POST "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events" \ -H "X-API-Key: $TBIT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Empezó la prueba gratis", "description": "Termina el 15 de octubre", "occurred_at": "2026-10-08T15:00:00Z", "idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08", "data": { "plan": "monthly" } }' ``` Respuesta: ```json { "data": { "id": "6ac85d7e32e0335e1dcac4fd", "contact_id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Empezó la prueba gratis", "occurred_at": "2026-10-08T15:00:00.000Z", "duplicate": false } } ``` ## Formato de Respuesta Los endpoints de listado retornan resultados paginados: ```json { "data": [ { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "profile_name": "Jane Doe", "email": "[email protected]", "notes": "Preferred language: English", "channels": [ { "channel_id": "573001234567", "channel_type": "whatsapp" } ], "custom_attributes": { "city": "Bogota", "plan": "premium" }, "created_at": "2024-09-01T12:00:00Z", "updated_at": "2024-09-01T14:30:00Z" } ], "pagination": { "total": 50, "limit": 20, "offset": 0, "has_more": true } } ```Los contactos representan las personas que interactúan con tu agente a través de canales como WhatsApp, Instagram y email. Cada contacto tiene un perfil con nombre, identificadores de canal y metadatos opcionales.
| Método | Ruta | Descripción |
|---|---|---|
| GET | /v1/contacts | Listar contactos |
| GET | /v1/contacts/:id | Ver el detalle de un contacto |
| POST | /v1/contacts | Crear un contacto |
| PATCH | /v1/contacts/:id | Actualizar un contacto |
| PUT | /v1/contacts | Crear o actualizar por teléfono o correo (upsert) |
| GET | /v1/contacts?phone=|email= | Buscar contactos por teléfono o correo |
| PATCH | /v1/contacts/:id/attributes | Guardar atributos del contacto |
| PUT | /v1/contacts/:id/stage | Poner al contacto en una etapa de un embudo |
| POST | /v1/contacts/:id/events | Agregar un evento a su línea de tiempo |
El endpoint de listado soporta los siguientes parámetros de consulta:
| Parámetro | Tipo | Descripción |
|---|---|---|
limit | number | Resultados por página (predeterminado: 20, máximo: 100) |
offset | number | Número de resultados a omitir (predeterminado: 0) |
/v1/contactscurl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts?limit=20&offset=0', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts?limit=20&offset=0',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts?limit=20&offset=0',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts?limit=20&offset=0');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1curl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"profile_name": "Jane Doe",
"email": "[email protected]",
"notes": "Preferred language: English"
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1', {
method: 'PATCH',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
profile_name: 'Jane Doe',
email: '[email protected]',
notes: 'Preferred language: English',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
{
profile_name: 'Jane Doe',
email: '[email protected]',
notes: 'Preferred language: English',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'profile_name': 'Jane Doe',
'email': '[email protected]',
'notes': 'Preferred language: English',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'profile_name' => 'Jane Doe',
'email' => '[email protected]',
'notes' => 'Preferred language: English',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);Los custom_attributes se validan con las mismas reglas de «Guardar atributos» antes de escribir nada. Si un valor no sirve responde 400 VALIDATION_ERROR con el motivo de cada clave (Invalid custom_attributes: «clave»: «motivo») y no se guarda ni el contacto ni sus atributos. Un atributo que no existe se crea con el tipo deducido del valor.
/v1/contactscurl -X POST "https://rest-api.tbit.app/v1/contacts" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel_id": "573009876543",
"channel_type": "whatsapp",
"profile_name": "Jane Doe",
"custom_attributes": {
"city": "Bogota",
"plan": "premium"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
channel_id: '573009876543',
channel_type: 'whatsapp',
profile_name: 'Jane Doe',
custom_attributes: {
city: 'Bogota',
plan: 'premium',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/contacts',
{
channel_id: '573009876543',
channel_type: 'whatsapp',
profile_name: 'Jane Doe',
custom_attributes: {
city: 'Bogota',
plan: 'premium',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/contacts',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'channel_id': '573009876543',
'channel_type': 'whatsapp',
'profile_name': 'Jane Doe',
'custom_attributes': {
'city': 'Bogota',
'plan': 'premium',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'channel_id' => '573009876543',
'channel_type' => 'whatsapp',
'profile_name' => 'Jane Doe',
'custom_attributes' => [
'city' => 'Bogota',
'plan' => 'premium',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);Busca el contacto de tu agente por su WhatsApp (E.164, con o sin «+») y, si no aparece, por su correo. Si no existe, lo crea; si existe, le agrega el canal que le falte. Nunca pisa un nombre que el contacto ya tenga. Responde 201 cuando lo crea y 200 cuando lo encuentra.
Si el teléfono y el correo son de dos contactos distintos responde 409 CONTACT_CONFLICT con los dos ids y no escribe nada. Los atributos que mandes se validan antes de tocar el contacto (ver «Guardar atributos»).
/v1/contactscurl -X PUT "https://rest-api.tbit.app/v1/contacts" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone": "+573001234567",
"email": "[email protected]",
"first_name": "Ana",
"last_name": "Pérez",
"attributes": {
"plan": "premium"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts', {
method: 'PUT',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
phone: '+573001234567',
email: '[email protected]',
first_name: 'Ana',
last_name: 'Pérez',
attributes: {
plan: 'premium',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.put(
'https://rest-api.tbit.app/v1/contacts',
{
phone: '+573001234567',
email: '[email protected]',
first_name: 'Ana',
last_name: 'Pérez',
attributes: {
plan: 'premium',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.put(
'https://rest-api.tbit.app/v1/contacts',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'phone': '+573001234567',
'email': '[email protected]',
'first_name': 'Ana',
'last_name': 'Pérez',
'attributes': {
'plan': 'premium',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'phone' => '+573001234567',
'email' => '[email protected]',
'first_name' => 'Ana',
'last_name' => 'Pérez',
'attributes' => [
'plan' => 'premium',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"created": true,
"matched_by": null,
"contact": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"first_name": "Ana",
"last_name": "Pérez",
"profile_name": "Ana Pérez",
"phone": "573001234567",
"email": "[email protected]",
"channels": [
{
"channel_type": "whatsapp",
"channel_id": "573001234567"
},
{
"channel_type": "email",
"channel_id": "[email protected]"
}
],
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"stages": [
{
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"funnel_name": "Clientes",
"stage": "prueba",
"stage_name": "En prueba"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-08T15:00:00.000Z"
}
}
}Devuelve hasta 10 contactos de tu agente que tengan ese WhatsApp (en cualquiera de sus grafías) o ese correo, con sus atributos y las etapas de embudo en las que están. Sin phone ni email, el endpoint sigue siendo el listado paginado de siempre.
/v1/contactscurl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \
-H "X-API-Key: $TBIT_API_KEY"const response = await fetch('https://rest-api.tbit.app/v1/contacts?email=ana%40example.com', {
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.get(
'https://rest-api.tbit.app/v1/contacts?email=ana%40example.com',
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.get(
'https://rest-api.tbit.app/v1/contacts?email=ana%40example.com',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts?email=ana%40example.com');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"first_name": "Ana",
"last_name": "Pérez",
"profile_name": "Ana Pérez",
"phone": "573001234567",
"email": "[email protected]",
"channels": [
{
"channel_type": "whatsapp",
"channel_id": "573001234567"
},
{
"channel_type": "email",
"channel_id": "[email protected]"
}
],
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"stages": [
{
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"funnel_name": "Clientes",
"stage": "prueba",
"stage_name": "En prueba"
}
],
"created_at": "2026-10-01T12:00:00.000Z",
"updated_at": "2026-10-08T15:00:00.000Z"
}
]
}Las claves son el NOMBRE del atributo, tal como se ve en «Datos del contacto» (sin importar mayúsculas ni tildes). Todo o nada: si una clave no existe responde 422 UNKNOWN_ATTRIBUTES con la lista en details.missing, y si un valor no cabe en su tipo (una opción que no está en la lista, un número que no es número, una fecha que no se puede leer) responde 422 INVALID_VALUE; en los dos casos no se guarda ninguno.
Fechas: se aceptan cuatro formas: fecha completa (2026-11-14), año y mes (2026-11), día y mes sin año (--11-14) o solo el mes (--11). Una fecha con hora (2026-11-14T15:00:00Z) se guarda como su día, y la API la devuelve siempre sin hora (2026-11-14). Listas de objetos, como «Fechas especiales»: cada ítem se valida contra su esquema. Los campos de fecha usan esas cuatro formas, los obligatorios no pueden ir vacíos y los de opciones deben ser una de la lista (sin importar mayúsculas ni tildes; se guarda escrita como la opción).
Con create_missing: true se crean los que falten (el tipo se deduce del valor). null borra el valor. Cada valor nuevo cuenta como «atributo llenado»: un embudo con una regla por ese atributo mueve la tarjeta igual que cuando lo llena la IA.
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributescurl -X PATCH "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"create_missing": false
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes', {
method: 'PATCH',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
attributes: {
plan: 'premium',
ciudad: 'Bogotá',
},
create_missing: false,
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes',
{
attributes: {
plan: 'premium',
ciudad: 'Bogotá',
},
create_missing: false,
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.patch(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'attributes': {
'plan': 'premium',
'ciudad': 'Bogotá',
},
'create_missing': False,
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/attributes');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'attributes' => [
'plan' => 'premium',
'ciudad' => 'Bogotá',
],
'create_missing' => false,
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"attributes": {
"plan": "premium",
"ciudad": "Bogotá"
},
"updated": [
"plan",
"ciudad"
],
"created_attributes": []
}
}Indica el embudo por funnel_id o por su nombre (funnel) y la etapa por su slug. Si el contacto no está en ese embudo lo agrega; si está en otra etapa lo mueve; si ya está ahí no hace nada (changed: false). Corren las acciones de entrada de la etapa y queda en el historial del contacto.
Por defecto no suena la campana del equipo: manda notify: true si quieres el aviso. Errores: 404 FUNNEL_NOT_FOUND y 422 UNKNOWN_STAGE (con la lista de etapas).
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stagecurl -X PUT "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"funnel": "Clientes",
"stage": "prueba"
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage', {
method: 'PUT',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
funnel: 'Clientes',
stage: 'prueba',
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.put(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage',
{
funnel: 'Clientes',
stage: 'prueba',
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.put(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'funnel': 'Clientes',
'stage': 'prueba',
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'funnel' => 'Clientes',
'stage' => 'prueba',
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa",
"stage": "prueba",
"previous_stage": "registrado",
"changed": true
}
}Deja un hito en la ficha del contacto, con su fecha (occurred_at, por defecto ahora; no puede ser futura). Con idempotency_key el mismo evento no se duplica: repetir la llamada responde 200 con duplicate: true y el evento original. data acepta hasta 20 claves con texto, número o booleano.
Los contactos de otro agente responden 404, igual que uno que no existe.
/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/eventscurl -X POST "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events" \
-H "X-API-Key: $TBIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Empezó la prueba gratis",
"description": "Termina el 15 de octubre",
"occurred_at": "2026-10-08T15:00:00Z",
"idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08",
"data": {
"plan": "monthly"
}
}'const response = await fetch('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events', {
method: 'POST',
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Empezó la prueba gratis',
description: 'Termina el 15 de octubre',
occurred_at: '2026-10-08T15:00:00Z',
idempotency_key: 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
data: {
plan: 'monthly',
},
}),
});
const data = await response.json();import axios from 'axios';
const { data } = await axios.post(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events',
{
name: 'Empezó la prueba gratis',
description: 'Termina el 15 de octubre',
occurred_at: '2026-10-08T15:00:00Z',
idempotency_key: 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
data: {
plan: 'monthly',
},
},
{
headers: {
'X-API-Key': process.env.TBIT_API_KEY,
},
},
);import os
import requests
response = requests.post(
'https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events',
headers={'X-API-Key': os.environ['TBIT_API_KEY']},
json={
'name': 'Empezó la prueba gratis',
'description': 'Termina el 15 de octubre',
'occurred_at': '2026-10-08T15:00:00Z',
'idempotency_key': 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
'data': {
'plan': 'monthly',
},
},
)
data = response.json()<?php
$ch = curl_init('https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-API-Key: ' . getenv('TBIT_API_KEY'),
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Empezó la prueba gratis',
'description' => 'Termina el 15 de octubre',
'occurred_at' => '2026-10-08T15:00:00Z',
'idempotency_key' => 'trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08',
'data' => [
'plan' => 'monthly',
],
]),
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);{
"data": {
"id": "6ac85d7e32e0335e1dcac4fd",
"contact_id": "64f1a2b3c4d5e6f7a8b9c0d1",
"name": "Empezó la prueba gratis",
"occurred_at": "2026-10-08T15:00:00.000Z",
"duplicate": false
}
}Los endpoints de listado retornan resultados paginados:
{
"data": [
{
"id": "64f1a2b3c4d5e6f7a8b9c0d1",
"profile_name": "Jane Doe",
"email": "[email protected]",
"notes": "Preferred language: English",
"channels": [
{
"channel_id": "573001234567",
"channel_type": "whatsapp"
}
],
"custom_attributes": {
"city": "Bogota",
"plan": "premium"
},
"created_at": "2024-09-01T12:00:00Z",
"updated_at": "2024-09-01T14:30:00Z"
}
],
"pagination": {
"total": 50,
"limit": 20,
"offset": 0,
"has_more": true
}
}