API
Contatos
Consulte e atualize informações de contatos
# Contatos > Consulte e atualize informações de contatos - Página: https://tbit.app/pt/docs/api/contacts - URL base: `https://rest-api.tbit.app/v1` - Autenticação: cabeçalho `X-API-Key` com a sua chave em cada requisição (os exemplos a leem da variável de ambiente `TBIT_API_KEY`) ## Visão geral Os contatos representam as pessoas que interagem com o seu agente através de canais como WhatsApp, Instagram e email. Cada contato tem um perfil com nome, identificadores de canal e metadados opcionais. ## Endpoints | Método | Rota | Descrição | | --- | --- | --- | | `GET` | `/v1/contacts` | Listar contatos | | `GET` | `/v1/contacts/:id` | Ver o detalhe de um contato | | `POST` | `/v1/contacts` | Criar um contato | | `PATCH` | `/v1/contacts/:id` | Atualizar um contato | | `PUT` | `/v1/contacts` | Criar ou atualizar por telefone ou email (upsert) | | `GET` | `/v1/contacts?phone=\|email=` | Buscar contatos por telefone ou email | | `PATCH` | `/v1/contacts/:id/attributes` | Salvar atributos do contato | | `PUT` | `/v1/contacts/:id/stage` | Colocar o contato em uma etapa de um funil | | `POST` | `/v1/contacts/:id/events` | Adicionar um evento à sua linha do tempo | ## Parâmetros de consulta O endpoint de listagem suporta os seguintes parâmetros de consulta: | Parâmetro | Tipo | Descrição | | --- | --- | --- | | `limit` | `number` | Resultados por página (padrão: 20, máximo: 100) | | `offset` | `number` | Número de resultados a omitir (padrão: 0) | ## Listar Contatos `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Obter Detalhe de Contato `GET /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Atualizar Contato `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" }' ``` ## Criar Contato Os custom_attributes são validados com as mesmas regras de «Salvar atributos» antes de escrever qualquer coisa. Se um valor não servir, responde 400 VALIDATION_ERROR com o motivo de cada chave (Invalid custom_attributes: «chave»: «motivo») e não se salva nem o contato nem os seus atributos. Um atributo que não existe é criado com o tipo deduzido do 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" } }' ``` ## Criar ou atualizar por telefone ou email Busca o contato do seu agente pelo seu WhatsApp (E.164, com ou sem «+») e, se não aparecer, pelo seu email. Se não existir, cria; se existir, adiciona o canal que faltar. Nunca sobrescreve um nome que o contato já tenha. Responde 201 quando cria e 200 quando encontra. Se o telefone e o email forem de dois contatos distintos, responde 409 CONTACT_CONFLICT com os dois ids e não escreve nada. Os atributos que você enviar são validados antes de tocar no contato (ver «Salvar 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" } }' ``` Resposta: ```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 telefone ou email Retorna até 10 contatos do seu agente que tenham esse WhatsApp (em qualquer das suas grafias) ou esse email, com os seus atributos e as etapas de funil em que estão. Sem phone nem email, o endpoint continua sendo a listagem paginada de sempre. `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \ -H "X-API-Key: $TBIT_API_KEY" ``` Resposta: ```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" } ] } ``` ## Salvar atributos As chaves são o NOME do atributo, tal como se vê em «Dados do contato» (sem importar maiúsculas nem acentos). Tudo ou nada: se uma chave não existe, responde 422 UNKNOWN_ATTRIBUTES com a lista em details.missing, e se um valor não cabe no seu tipo (uma opção que não está na lista, um número que não é número, uma data que não se pode ler) responde 422 INVALID_VALUE; nos dois casos não se salva nenhum. Datas: são aceitas quatro formas: data completa (2026-11-14), ano e mês (2026-11), dia e mês sem ano (--11-14) ou apenas o mês (--11). Uma data com hora (2026-11-14T15:00:00Z) é guardada como o seu dia, e a API a devolve sempre sem hora (2026-11-14). Listas de objetos, como «Datas especiais»: cada item é validado contra o seu esquema. Os campos de data usam essas quatro formas, os obrigatórios não podem ir vazios e os de opções devem ser uma da lista (sem importar maiúsculas nem acentos; é guardada escrita como a opção). Com create_missing: true são criados os que faltarem (o tipo é deduzido do valor). null apaga o valor. Cada valor novo conta como «atributo preenchido»: um funil com uma regra por esse atributo move o cartão igual a quando o preenche a 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 }' ``` Resposta: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "updated": [ "plan", "ciudad" ], "created_attributes": [] } } ``` ## Colocar em uma etapa de um funil Indica o funil por funnel_id ou pelo seu nome (funnel) e a etapa pelo seu slug. Se o contato não está nesse funil o adiciona; se está em outra etapa o move; se já está aí não faz nada (changed: false). Correm as ações de entrada da etapa e fica no histórico do contato. Por padrão não soa a campainha da equipe: manda notify: true se quiser o aviso. Erros: 404 FUNNEL_NOT_FOUND e 422 UNKNOWN_STAGE (com a 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" }' ``` Resposta: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "stage": "prueba", "previous_stage": "registrado", "changed": true } } ``` ## Adicionar um evento à linha do tempo Deixa um marco na ficha do contato, com a sua data (occurred_at, por padrão agora; não pode ser futura). Com idempotency_key o mesmo evento não se duplica: repetir a chamada responde 200 com duplicate: true e o evento original. data aceita até 20 chaves com texto, número ou booleano. Os contatos de outro agente respondem 404, igual a um que não 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" } }' ``` Resposta: ```json { "data": { "id": "6ac85d7e32e0335e1dcac4fd", "contact_id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Empezó la prueba gratis", "occurred_at": "2026-10-08T15:00:00.000Z", "duplicate": false } } ``` ## Formato de Resposta Os endpoints de listagem retornam 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 } } ```Os contatos representam as pessoas que interagem com o seu agente através de canais como WhatsApp, Instagram e email. Cada contato tem um perfil com nome, identificadores de canal e metadados opcionais.
| Método | Rota | Descrição |
|---|---|---|
| GET | /v1/contacts | Listar contatos |
| GET | /v1/contacts/:id | Ver o detalhe de um contato |
| POST | /v1/contacts | Criar um contato |
| PATCH | /v1/contacts/:id | Atualizar um contato |
| PUT | /v1/contacts | Criar ou atualizar por telefone ou email (upsert) |
| GET | /v1/contacts?phone=|email= | Buscar contatos por telefone ou email |
| PATCH | /v1/contacts/:id/attributes | Salvar atributos do contato |
| PUT | /v1/contacts/:id/stage | Colocar o contato em uma etapa de um funil |
| POST | /v1/contacts/:id/events | Adicionar um evento à sua linha do tempo |
O endpoint de listagem suporta os seguintes parâmetros de consulta:
| Parâmetro | Tipo | Descrição |
|---|---|---|
limit | number | Resultados por página (padrão: 20, máximo: 100) |
offset | number | Número de resultados a omitir (padrão: 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);Os custom_attributes são validados com as mesmas regras de «Salvar atributos» antes de escrever qualquer coisa. Se um valor não servir, responde 400 VALIDATION_ERROR com o motivo de cada chave (Invalid custom_attributes: «chave»: «motivo») e não se salva nem o contato nem os seus atributos. Um atributo que não existe é criado com o tipo deduzido do 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 o contato do seu agente pelo seu WhatsApp (E.164, com ou sem «+») e, se não aparecer, pelo seu email. Se não existir, cria; se existir, adiciona o canal que faltar. Nunca sobrescreve um nome que o contato já tenha. Responde 201 quando cria e 200 quando encontra.
Se o telefone e o email forem de dois contatos distintos, responde 409 CONTACT_CONFLICT com os dois ids e não escreve nada. Os atributos que você enviar são validados antes de tocar no contato (ver «Salvar 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"
}
}
}Retorna até 10 contatos do seu agente que tenham esse WhatsApp (em qualquer das suas grafias) ou esse email, com os seus atributos e as etapas de funil em que estão. Sem phone nem email, o endpoint continua sendo a listagem paginada de sempre.
/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"
}
]
}As chaves são o NOME do atributo, tal como se vê em «Dados do contato» (sem importar maiúsculas nem acentos). Tudo ou nada: se uma chave não existe, responde 422 UNKNOWN_ATTRIBUTES com a lista em details.missing, e se um valor não cabe no seu tipo (uma opção que não está na lista, um número que não é número, uma data que não se pode ler) responde 422 INVALID_VALUE; nos dois casos não se salva nenhum.
Datas: são aceitas quatro formas: data completa (2026-11-14), ano e mês (2026-11), dia e mês sem ano (--11-14) ou apenas o mês (--11). Uma data com hora (2026-11-14T15:00:00Z) é guardada como o seu dia, e a API a devolve sempre sem hora (2026-11-14). Listas de objetos, como «Datas especiais»: cada item é validado contra o seu esquema. Os campos de data usam essas quatro formas, os obrigatórios não podem ir vazios e os de opções devem ser uma da lista (sem importar maiúsculas nem acentos; é guardada escrita como a opção).
Com create_missing: true são criados os que faltarem (o tipo é deduzido do valor). null apaga o valor. Cada valor novo conta como «atributo preenchido»: um funil com uma regra por esse atributo move o cartão igual a quando o preenche a 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 o funil por funnel_id ou pelo seu nome (funnel) e a etapa pelo seu slug. Se o contato não está nesse funil o adiciona; se está em outra etapa o move; se já está aí não faz nada (changed: false). Correm as ações de entrada da etapa e fica no histórico do contato.
Por padrão não soa a campainha da equipe: manda notify: true se quiser o aviso. Erros: 404 FUNNEL_NOT_FOUND e 422 UNKNOWN_STAGE (com a 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
}
}Deixa um marco na ficha do contato, com a sua data (occurred_at, por padrão agora; não pode ser futura). Com idempotency_key o mesmo evento não se duplica: repetir a chamada responde 200 com duplicate: true e o evento original. data aceita até 20 chaves com texto, número ou booleano.
Os contatos de outro agente respondem 404, igual a um que não 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
}
}Os endpoints de listagem retornam 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
}
}