Skip to content
Menu

Search the site

Type to search guides, blog, API and product.

↑ ↓ to move · Enter to open · Esc to close

API Reference

API

Contacts

Retrieve and update contact information

View as Markdown

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.

MethodPathDescription
GET/v1/contactsList contacts
GET/v1/contacts/:idGet contact detail
POST/v1/contactsCreate a new contact
PATCH/v1/contacts/:idUpdate contact
PUT/v1/contactsCreate or update by phone or email (upsert)
GET/v1/contacts?phone=|email=Find contacts by phone or email
PATCH/v1/contacts/:id/attributesSave contact attributes
PUT/v1/contacts/:id/stagePut the contact in a funnel stage
POST/v1/contacts/:id/eventsAdd an event to its timeline

The list endpoint supports the following query parameters:

ParameterTypeDescription
limitnumberResults per page (default: 20, max: 100)
offsetnumberNumber of results to skip (default: 0)

List Contacts

GET/v1/contacts
curl "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);

Get Contact Detail

GET/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1
curl "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);

Update Contact

PATCH/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1
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"
  }'
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);

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
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"
    }
  }'
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»).

PUT/v1/contacts
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"
    }
  }'
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);
Response
{
  "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.

GET/v1/contacts
curl "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);
Response
{
  "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
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
  }'
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);
Response
{
  "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).

PUT/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/stage
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"
  }'
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);
Response
{
  "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.

POST/v1/contacts/64f1a2b3c4d5e6f7a8b9c0d1/events
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"
    }
  }'
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);
Response
{
  "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:

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