API
Contacts
Retrieve and update contact information
# Contacts > Retrieve and update contact information - Page: https://tbit.app/docs/api/contacts - Base URL: `https://rest-api.tbit.app/v1` - Authentication: `X-API-Key` header with your key on every request (the examples read it from the `TBIT_API_KEY` environment variable) ## Overview Contacts represent the people who interact with your agent across channels such as WhatsApp, Instagram, and email. Each contact has a profile with name, channel identifiers, and optional metadata. ## Endpoints | Method | Path | Description | | --- | --- | --- | | `GET` | `/v1/contacts` | List contacts | | `GET` | `/v1/contacts/:id` | Get contact detail | | `POST` | `/v1/contacts` | Create a new contact | | `PATCH` | `/v1/contacts/:id` | Update contact | | `PUT` | `/v1/contacts` | Create or update by phone or email (upsert) | | `GET` | `/v1/contacts?phone=\|email=` | Find contacts by phone or email | | `PATCH` | `/v1/contacts/:id/attributes` | Save contact attributes | | `PUT` | `/v1/contacts/:id/stage` | Put the contact in a funnel stage | | `POST` | `/v1/contacts/:id/events` | Add an event to its timeline | ## Query Parameters The list endpoint supports the following query parameters: | Parameter | Type | Description | | --- | --- | --- | | `limit` | `number` | Results per page (default: 20, max: 100) | | `offset` | `number` | Number of results to skip (default: 0) | ## List Contacts `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Get Contact Detail `GET /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Update Contact `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" }' ``` ## Create Contact custom_attributes are validated with the same rules as «Save attributes» before anything is written. If a value does not fit, it answers 400 VALIDATION_ERROR with the reason for each key (Invalid custom_attributes: «key»: «reason») and neither the contact nor its attributes are saved. An attribute that does not exist is created with the type inferred from the value. `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" } }' ``` ## Create or update by phone or email Finds your agent's contact by WhatsApp number (E.164, with or without «+») and, failing that, by email. Creates it when missing; when it exists, attaches the channel it lacks. It never overwrites a name the contact already has. Answers 201 when it creates and 200 when it finds. If the phone and the email belong to two different contacts it answers 409 CONTACT_CONFLICT with both ids and writes nothing. Attributes you send are validated before the contact is touched (see «Save attributes»). `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" } }' ``` Response: ```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" } } } ``` ## Find by phone or email Returns up to 10 of your agent's contacts with that WhatsApp number (any spelling) or that email, with their attributes and the funnel stages they are in. Without phone or email the endpoint keeps being the usual paginated list. `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \ -H "X-API-Key: $TBIT_API_KEY" ``` Response: ```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" } ] } ``` ## Save attributes Keys are the attribute NAME as shown in «Contact data» (case and accent insensitive). All or nothing: an unknown key answers 422 UNKNOWN_ATTRIBUTES listing them in details.missing, and a value that does not fit its type (an option not in the list, a non-number, a date that cannot be read) answers 422 INVALID_VALUE; in both cases nothing is saved. Dates: four forms are accepted: full date (2026-11-14), year and month (2026-11), day and month without year (--11-14) or month only (--11). A date with a time (2026-11-14T15:00:00Z) is stored as its day, and the API always returns it without the time (2026-11-14). Lists of objects, like «Fechas especiales»: each item is validated against its schema. Date fields take those four forms, required fields cannot be empty and option fields must be one of the list (case and accent insensitive; stored as the option is written). With create_missing: true the missing ones are created (type inferred from the value). null clears the value. Every new value counts as «attribute filled»: a funnel rule on that attribute moves the card just like when the AI fills it. `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 }' ``` Response: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "updated": [ "plan", "ciudad" ], "created_attributes": [] } } ``` ## Put in a funnel stage Name the funnel by funnel_id or by name (funnel) and the stage by its slug. If the contact is not in that funnel it is added; if it is in another stage it is moved; if it is already there nothing happens (changed: false). The stage entry actions run and the move is kept in the contact history. By default the team bell does not ring: send notify: true if you want the notice. Errors: 404 FUNNEL_NOT_FOUND and 422 UNKNOWN_STAGE (with the stage list). `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" }' ``` Response: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "stage": "prueba", "previous_stage": "registrado", "changed": true } } ``` ## Add an event to the timeline Leaves a milestone on the contact card with its date (occurred_at, default now; it cannot be in the future). With idempotency_key the same event is never duplicated: repeating the call answers 200 with duplicate: true and the original event. data takes up to 20 keys of text, number or boolean. Contacts of another agent answer 404, just like one that does not exist. `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": "Started the free trial", "description": "Ends on October 15", "occurred_at": "2026-10-08T15:00:00Z", "idempotency_key": "trial:64f1a2b3c4d5e6f7a8b9c0d1:2026-10-08", "data": { "plan": "monthly" } }' ``` Response: ```json { "data": { "id": "6ac85d7e32e0335e1dcac4fd", "contact_id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Started the free trial", "occurred_at": "2026-10-08T15:00:00.000Z", "duplicate": false } } ``` ## Response Format List endpoints return paginated results: ```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 } } ```Contacts represent the people who interact with your agent across channels such as WhatsApp, Instagram, and email. Each contact has a profile with name, channel identifiers, and optional metadata.
| Method | Path | Description |
|---|---|---|
| GET | /v1/contacts | List contacts |
| GET | /v1/contacts/:id | Get contact detail |
| POST | /v1/contacts | Create a new contact |
| PATCH | /v1/contacts/:id | Update contact |
| PUT | /v1/contacts | Create or update by phone or email (upsert) |
| GET | /v1/contacts?phone=|email= | Find contacts by phone or email |
| PATCH | /v1/contacts/:id/attributes | Save contact attributes |
| PUT | /v1/contacts/:id/stage | Put the contact in a funnel stage |
| POST | /v1/contacts/:id/events | Add an event to its timeline |
The list endpoint supports the following query parameters:
| Parameter | Type | Description |
|---|---|---|
limit | number | Results per page (default: 20, max: 100) |
offset | number | Number of results to skip (default: 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);custom_attributes are validated with the same rules as «Save attributes» before anything is written. If a value does not fit, it answers 400 VALIDATION_ERROR with the reason for each key (Invalid custom_attributes: «key»: «reason») and neither the contact nor its attributes are saved. An attribute that does not exist is created with the type inferred from the value.
/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);Finds your agent's contact by WhatsApp number (E.164, with or without «+») and, failing that, by email. Creates it when missing; when it exists, attaches the channel it lacks. It never overwrites a name the contact already has. Answers 201 when it creates and 200 when it finds.
If the phone and the email belong to two different contacts it answers 409 CONTACT_CONFLICT with both ids and writes nothing. Attributes you send are validated before the contact is touched (see «Save attributes»).
/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"
}
}
}Returns up to 10 of your agent's contacts with that WhatsApp number (any spelling) or that email, with their attributes and the funnel stages they are in. Without phone or email the endpoint keeps being the usual paginated list.
/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"
}
]
}Keys are the attribute NAME as shown in «Contact data» (case and accent insensitive). All or nothing: an unknown key answers 422 UNKNOWN_ATTRIBUTES listing them in details.missing, and a value that does not fit its type (an option not in the list, a non-number, a date that cannot be read) answers 422 INVALID_VALUE; in both cases nothing is saved.
Dates: four forms are accepted: full date (2026-11-14), year and month (2026-11), day and month without year (--11-14) or month only (--11). A date with a time (2026-11-14T15:00:00Z) is stored as its day, and the API always returns it without the time (2026-11-14). Lists of objects, like «Fechas especiales»: each item is validated against its schema. Date fields take those four forms, required fields cannot be empty and option fields must be one of the list (case and accent insensitive; stored as the option is written).
With create_missing: true the missing ones are created (type inferred from the value). null clears the value. Every new value counts as «attribute filled»: a funnel rule on that attribute moves the card just like when the AI fills it.
/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": []
}
}Name the funnel by funnel_id or by name (funnel) and the stage by its slug. If the contact is not in that funnel it is added; if it is in another stage it is moved; if it is already there nothing happens (changed: false). The stage entry actions run and the move is kept in the contact history.
By default the team bell does not ring: send notify: true if you want the notice. Errors: 404 FUNNEL_NOT_FOUND and 422 UNKNOWN_STAGE (with the stage list).
/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
}
}Leaves a milestone on the contact card with its date (occurred_at, default now; it cannot be in the future). With idempotency_key the same event is never duplicated: repeating the call answers 200 with duplicate: true and the original event. data takes up to 20 keys of text, number or boolean.
Contacts of another agent answer 404, just like one that does not exist.
/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": "Started the free trial",
"description": "Ends on October 15",
"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: 'Started the free trial',
description: 'Ends on October 15',
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: 'Started the free trial',
description: 'Ends on October 15',
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': 'Started the free trial',
'description': 'Ends on October 15',
'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' => 'Started the free trial',
'description' => 'Ends on October 15',
'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": "Started the free trial",
"occurred_at": "2026-10-08T15:00:00.000Z",
"duplicate": false
}
}List endpoints return paginated results:
{
"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
}
}