API
Kontakte
Rufe Kontaktinformationen ab und aktualisiere sie
# Kontakte > Rufe Kontaktinformationen ab und aktualisiere sie - Seite: https://tbit.app/de/docs/api/contacts - Basis-URL: `https://rest-api.tbit.app/v1` - Authentifizierung: Header `X-API-Key` mit deinem Schlüssel in jeder Anfrage (die Beispiele lesen ihn aus der Umgebungsvariable `TBIT_API_KEY`) ## Überblick Kontakte stehen für die Personen, die mit deinem Agenten über Kanäle wie WhatsApp, Instagram und E-Mail interagieren. Jeder Kontakt hat ein Profil mit Name, Kanal-Identifikatoren und optionalen Metadaten. ## Endpunkte | Methode | Route | Beschreibung | | --- | --- | --- | | `GET` | `/v1/contacts` | Kontakte auflisten | | `GET` | `/v1/contacts/:id` | Details eines Kontakts ansehen | | `POST` | `/v1/contacts` | Einen Kontakt erstellen | | `PATCH` | `/v1/contacts/:id` | Einen Kontakt aktualisieren | | `PUT` | `/v1/contacts` | Per Telefon oder E-Mail erstellen oder aktualisieren (Upsert) | | `GET` | `/v1/contacts?phone=\|email=` | Kontakte per Telefon oder E-Mail suchen | | `PATCH` | `/v1/contacts/:id/attributes` | Attribute des Kontakts speichern | | `PUT` | `/v1/contacts/:id/stage` | Den Kontakt in eine Phase eines Trichters setzen | | `POST` | `/v1/contacts/:id/events` | Ein Ereignis zu seiner Zeitleiste hinzufügen | ## Abfrageparameter Der Listen-Endpunkt unterstützt die folgenden Abfrageparameter: | Parameter | Typ | Beschreibung | | --- | --- | --- | | `limit` | `number` | Ergebnisse pro Seite (Standard: 20, Maximum: 100) | | `offset` | `number` | Anzahl der zu überspringenden Ergebnisse (Standard: 0) | ## Kontakte auflisten `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?limit=20&offset=0" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Kontaktdetails abrufen `GET /v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1` ```bash curl "https://rest-api.tbit.app/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1" \ -H "X-API-Key: $TBIT_API_KEY" ``` ## Kontakt aktualisieren `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" }' ``` ## Kontakt erstellen Die custom_attributes werden mit denselben Regeln wie bei „Attribute speichern“ validiert, bevor etwas geschrieben wird. Wenn ein Wert nicht passt, antwortet der Dienst mit 400 VALIDATION_ERROR und dem Grund für jeden Schlüssel (Invalid custom_attributes: „Schlüssel“: „Grund“), und weder der Kontakt noch seine Attribute werden gespeichert. Ein Attribut, das nicht existiert, wird mit dem aus dem Wert abgeleiteten Typ erstellt. `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" } }' ``` ## Per Telefon oder E-Mail erstellen oder aktualisieren Sucht den Kontakt deines Agenten über seine WhatsApp (E.164, mit oder ohne „+“) und, falls er nicht gefunden wird, über seine E-Mail. Wenn er nicht existiert, wird er erstellt; wenn er existiert, wird ihm der fehlende Kanal hinzugefügt. Ein Name, den der Kontakt bereits hat, wird nie überschrieben. Antwortet mit 201, wenn er erstellt wird, und mit 200, wenn er gefunden wird. Wenn Telefon und E-Mail zu zwei verschiedenen Kontakten gehören, antwortet der Dienst mit 409 CONTACT_CONFLICT und den beiden ids, und schreibt nichts. Die Attribute, die du sendest, werden validiert, bevor der Kontakt berührt wird (siehe „Attribute speichern“). `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" } }' ``` Antwort: ```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" } } } ``` ## Per Telefon oder E-Mail suchen Gibt bis zu 10 Kontakte deines Agenten zurück, die diese WhatsApp (in jeder ihrer Schreibweisen) oder diese E-Mail haben, mit ihren Attributen und den Trichterphasen, in denen sie sich befinden. Ohne phone und email bleibt der Endpunkt die gewohnte paginierte Liste. `GET /v1/contacts` ```bash curl "https://rest-api.tbit.app/v1/contacts?email=ana%40example.com" \ -H "X-API-Key: $TBIT_API_KEY" ``` Antwort: ```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" } ] } ``` ## Attribute speichern Die Schlüssel sind der NAME des Attributs, so wie er in „Kontaktdaten“ erscheint (unabhängig von Groß- und Kleinschreibung oder Akzenten). Alles oder nichts: Wenn ein Schlüssel nicht existiert, antwortet der Dienst mit 422 UNKNOWN_ATTRIBUTES und der Liste in details.missing, und wenn ein Wert nicht in seinen Typ passt (eine Option, die nicht in der Liste steht, eine Zahl, die keine Zahl ist, ein Datum, das nicht gelesen werden kann), antwortet er mit 422 INVALID_VALUE; in beiden Fällen wird nichts gespeichert. Datumsangaben: vier Formen werden akzeptiert: vollständiges Datum (2026-11-14), Jahr und Monat (2026-11), Tag und Monat ohne Jahr (--11-14) oder nur der Monat (--11). Ein Datum mit Uhrzeit (2026-11-14T15:00:00Z) wird als sein Tag gespeichert, und die API gibt es immer ohne Uhrzeit zurück (2026-11-14). Listen von Objekten, wie „Besondere Daten“: jedes Element wird gegen sein Schema validiert. Die Datumsfelder verwenden diese vier Formen, die Pflichtfelder dürfen nicht leer sein und die Optionsfelder müssen eine aus der Liste sein (unabhängig von Groß- und Kleinschreibung oder Akzenten; gespeichert wird es so geschrieben wie die Option). Mit create_missing: true werden die fehlenden erstellt (der Typ wird aus dem Wert abgeleitet). null löscht den Wert. Jeder neue Wert zählt als „gefülltes Attribut“: ein Funnel mit einer Regel für dieses Attribut verschiebt die Karte genauso wie wenn die KI ihn füllt. `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 }' ``` Antwort: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "attributes": { "plan": "premium", "ciudad": "Bogotá" }, "updated": [ "plan", "ciudad" ], "created_attributes": [] } } ``` ## In eine Phase eines Funnels setzen Gib den Funnel über funnel_id oder seinen Namen (funnel) an und die Phase über ihren slug. Wenn der Kontakt nicht in diesem Funnel ist, wird er hinzugefügt; wenn er in einer anderen Phase ist, wird er verschoben; wenn er schon dort ist, passiert nichts (changed: false). Die Eintrittsaktionen der Phase laufen und es bleibt im Verlauf des Kontakts. Standardmäßig klingelt die Glocke des Teams nicht: sende notify: true, wenn du die Benachrichtigung willst. Fehler: 404 FUNNEL_NOT_FOUND und 422 UNKNOWN_STAGE (mit der Liste der Phasen). `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" }' ``` Antwort: ```json { "data": { "id": "64f1a2b3c4d5e6f7a8b9c0d1", "funnel_id": "64f1a2b3c4d5e6f7a8b9c0aa", "stage": "prueba", "previous_stage": "registrado", "changed": true } } ``` ## Ein Ereignis zur Zeitleiste hinzufügen Hinterlässt einen Meilenstein in der Karte des Kontakts, mit seinem Datum (occurred_at, standardmäßig jetzt; darf nicht in der Zukunft liegen). Mit idempotency_key wird dasselbe Ereignis nicht dupliziert: ein wiederholter Aufruf antwortet mit 200 und duplicate: true und dem ursprünglichen Ereignis. data akzeptiert bis zu 20 Schlüssel mit Text, Zahl oder Boolean. Kontakte eines anderen Agenten antworten mit 404, genauso wie einer, der nicht existiert. `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" } }' ``` Antwort: ```json { "data": { "id": "6ac85d7e32e0335e1dcac4fd", "contact_id": "64f1a2b3c4d5e6f7a8b9c0d1", "name": "Empezó la prueba gratis", "occurred_at": "2026-10-08T15:00:00.000Z", "duplicate": false } } ``` ## Antwortformat Die Listen-Endpunkte geben paginierte Ergebnisse zurück: ```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 } } ```Kontakte stehen für die Personen, die mit deinem Agenten über Kanäle wie WhatsApp, Instagram und E-Mail interagieren. Jeder Kontakt hat ein Profil mit Name, Kanal-Identifikatoren und optionalen Metadaten.
| Methode | Route | Beschreibung |
|---|---|---|
| GET | /v1/contacts | Kontakte auflisten |
| GET | /v1/contacts/:id | Details eines Kontakts ansehen |
| POST | /v1/contacts | Einen Kontakt erstellen |
| PATCH | /v1/contacts/:id | Einen Kontakt aktualisieren |
| PUT | /v1/contacts | Per Telefon oder E-Mail erstellen oder aktualisieren (Upsert) |
| GET | /v1/contacts?phone=|email= | Kontakte per Telefon oder E-Mail suchen |
| PATCH | /v1/contacts/:id/attributes | Attribute des Kontakts speichern |
| PUT | /v1/contacts/:id/stage | Den Kontakt in eine Phase eines Trichters setzen |
| POST | /v1/contacts/:id/events | Ein Ereignis zu seiner Zeitleiste hinzufügen |
Der Listen-Endpunkt unterstützt die folgenden Abfrageparameter:
| Parameter | Typ | Beschreibung |
|---|---|---|
limit | number | Ergebnisse pro Seite (Standard: 20, Maximum: 100) |
offset | number | Anzahl der zu überspringenden Ergebnisse (Standard: 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);Die custom_attributes werden mit denselben Regeln wie bei „Attribute speichern“ validiert, bevor etwas geschrieben wird. Wenn ein Wert nicht passt, antwortet der Dienst mit 400 VALIDATION_ERROR und dem Grund für jeden Schlüssel (Invalid custom_attributes: „Schlüssel“: „Grund“), und weder der Kontakt noch seine Attribute werden gespeichert. Ein Attribut, das nicht existiert, wird mit dem aus dem Wert abgeleiteten Typ erstellt.
/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);Sucht den Kontakt deines Agenten über seine WhatsApp (E.164, mit oder ohne „+“) und, falls er nicht gefunden wird, über seine E-Mail. Wenn er nicht existiert, wird er erstellt; wenn er existiert, wird ihm der fehlende Kanal hinzugefügt. Ein Name, den der Kontakt bereits hat, wird nie überschrieben. Antwortet mit 201, wenn er erstellt wird, und mit 200, wenn er gefunden wird.
Wenn Telefon und E-Mail zu zwei verschiedenen Kontakten gehören, antwortet der Dienst mit 409 CONTACT_CONFLICT und den beiden ids, und schreibt nichts. Die Attribute, die du sendest, werden validiert, bevor der Kontakt berührt wird (siehe „Attribute speichern“).
/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"
}
}
}Gibt bis zu 10 Kontakte deines Agenten zurück, die diese WhatsApp (in jeder ihrer Schreibweisen) oder diese E-Mail haben, mit ihren Attributen und den Trichterphasen, in denen sie sich befinden. Ohne phone und email bleibt der Endpunkt die gewohnte paginierte Liste.
/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"
}
]
}Die Schlüssel sind der NAME des Attributs, so wie er in „Kontaktdaten“ erscheint (unabhängig von Groß- und Kleinschreibung oder Akzenten). Alles oder nichts: Wenn ein Schlüssel nicht existiert, antwortet der Dienst mit 422 UNKNOWN_ATTRIBUTES und der Liste in details.missing, und wenn ein Wert nicht in seinen Typ passt (eine Option, die nicht in der Liste steht, eine Zahl, die keine Zahl ist, ein Datum, das nicht gelesen werden kann), antwortet er mit 422 INVALID_VALUE; in beiden Fällen wird nichts gespeichert.
Datumsangaben: vier Formen werden akzeptiert: vollständiges Datum (2026-11-14), Jahr und Monat (2026-11), Tag und Monat ohne Jahr (--11-14) oder nur der Monat (--11). Ein Datum mit Uhrzeit (2026-11-14T15:00:00Z) wird als sein Tag gespeichert, und die API gibt es immer ohne Uhrzeit zurück (2026-11-14). Listen von Objekten, wie „Besondere Daten“: jedes Element wird gegen sein Schema validiert. Die Datumsfelder verwenden diese vier Formen, die Pflichtfelder dürfen nicht leer sein und die Optionsfelder müssen eine aus der Liste sein (unabhängig von Groß- und Kleinschreibung oder Akzenten; gespeichert wird es so geschrieben wie die Option).
Mit create_missing: true werden die fehlenden erstellt (der Typ wird aus dem Wert abgeleitet). null löscht den Wert. Jeder neue Wert zählt als „gefülltes Attribut“: ein Funnel mit einer Regel für dieses Attribut verschiebt die Karte genauso wie wenn die KI ihn füllt.
/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": []
}
}Gib den Funnel über funnel_id oder seinen Namen (funnel) an und die Phase über ihren slug. Wenn der Kontakt nicht in diesem Funnel ist, wird er hinzugefügt; wenn er in einer anderen Phase ist, wird er verschoben; wenn er schon dort ist, passiert nichts (changed: false). Die Eintrittsaktionen der Phase laufen und es bleibt im Verlauf des Kontakts.
Standardmäßig klingelt die Glocke des Teams nicht: sende notify: true, wenn du die Benachrichtigung willst. Fehler: 404 FUNNEL_NOT_FOUND und 422 UNKNOWN_STAGE (mit der Liste der Phasen).
/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
}
}Hinterlässt einen Meilenstein in der Karte des Kontakts, mit seinem Datum (occurred_at, standardmäßig jetzt; darf nicht in der Zukunft liegen). Mit idempotency_key wird dasselbe Ereignis nicht dupliziert: ein wiederholter Aufruf antwortet mit 200 und duplicate: true und dem ursprünglichen Ereignis. data akzeptiert bis zu 20 Schlüssel mit Text, Zahl oder Boolean.
Kontakte eines anderen Agenten antworten mit 404, genauso wie einer, der nicht existiert.
/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
}
}Die Listen-Endpunkte geben paginierte Ergebnisse zurück:
{
"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
}
}