Pricing Developers

Product

Resources

Start free Log in

REST API reference

Contacts

Users and leads: create, update, search, tag, merge and delete the people you talk to.

A contact is a person: a user (someone your product knows, usually with an externalId) or a lead (an anonymous Messenger visitor). Reads need contacts:read; changes need contacts:write.

Creating people counts toward your plan’s contact limit. Changes made through the API update the inbox live and fire the same webhooks and workflows as changes made by teammates.

The contact object

Every response that returns a person uses this shape.

Fields

object string
Always contact.
id string
Unique id (UUID).
role enum
user (identified customer) or lead (anonymous visitor).
externalId string | null
Your product’s user id. Unique per workspace.
email string | null
Email address (lower-cased).
phone string | null
Phone number as entered.
name string | null
Full name.
avatarUrl string | null
Image URL.
ownerId string | null
Teammate who owns this person.
location object | null
city, region, country, countryCode and timezone, from the Messenger.
language string | null
Preferred language (de, pt-BR…).
browser string | null
Last browser seen by the Messenger.
os string | null
Last operating system seen by the Messenger.
lastSeenAt timestamp | null
Last activity in the Messenger.
lastContactedAt timestamp | null
Last message from your team.
lastRepliedAt timestamp | null
Last message from this person.
signedUpAt timestamp | null
When they signed up for your product.
sessionCount integer
Messenger sessions so far.
unsubscribedFromEmails boolean
Opted out of outbound emails.
blocked boolean
Blocked people can’t start conversations.
customAttributes object
Your data attributes by key.
tags array
Tags as { id, name }.
companies array
Companies as { id, name }.
createdAt timestamp
First seen.
updatedAt timestamp
Last change.
Example contact 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

List contacts

GET /v1 /contacts contacts:read

People, newest first by default. Pass email or externalId for an exact lookup (users before leads); the other filters narrow the list. The first page includes total.

Query parameters

role enum
user or lead.
email string
Exact email lookup.
externalId string
Exact lookup by your user id.
segmentId string
A saved segment id.
q string
Free text: name, email, phone or user id.
sort enum
name, email, lastSeenAt, createdAt, signedUpAt, sessionCount, lastContactedAt, lastRepliedAt. Default createdAt.
direction enum
asc or desc. Default desc.
limit integer
Items per page, 1–100. Default 25.
cursor string
The nextCursor of the previous page.
curl https://api.rabbitblaze.com/v1/contacts?role=user&limit=2 \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts?role=user&limit=2", {  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.get(    "https://api.rabbitblaze.com/v1/contacts",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    params={        "role": "user",        "limit": "2",    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "items": [    {      "object": "contact",      "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",      "role": "user",      "externalId": "usr_48213",      "email": "[email protected]",      "phone": "+49 30 1234567",      "name": "Lena Fischer",      "avatarUrl": null,      "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",      "location": {        "city": "Berlin",        "region": "Berlin",        "country": "Germany",        "countryCode": "DE",        "timezone": "Europe/Berlin"      },      "language": "de",      "browser": "Chrome",      "os": "macOS",      "lastSeenAt": "2026-10-02T13:58:20.000Z",      "lastContactedAt": "2026-10-02T14:11:08.000Z",      "lastRepliedAt": "2026-10-02T14:05:31.000Z",      "signedUpAt": "2025-03-08T10:00:00.000Z",      "sessionCount": 214,      "unsubscribedFromEmails": false,      "blocked": false,      "customAttributes": {        "plan": "business",        "seats": 12,        "mrr": 1490      },      "tags": [        {          "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",          "name": "VIP"        }      ],      "companies": [        {          "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",          "name": "Northwind Analytics"        }      ],      "createdAt": "2026-09-14T09:12:44.000Z",      "updatedAt": "2026-10-02T16:40:03.000Z"    }  ],  "nextCursor": "WyIyMDI2LTEwLTAyVDE0OjA1OjMxLjAwMFoiLCIwMTk5YzUyMC03ZThmIl0",  "total": 1284}

Search contacts

POST /v1 /contacts/search contacts:read

Filter people with the same rules as segments: filter is a rule group of attribute paths (contact.email, contact.custom.plan, company.name, contact.tags…) and operators (eq, contains, gt, within_last_days, in…). Groups nest with and / or.

Body

query string
Free text, like q above.
filter rule group
{ combinator: 'and' | 'or', rules: [{ attribute, operator, value? } | group] }.
role enum
user or lead.
segmentId string
Only people in this segment.
sort enum
Same fields as listing.
direction enum
asc or desc.
limit integer
Items per page, 1–100. Default 25.
cursor string
The nextCursor of the previous page.
curl -X POST https://api.rabbitblaze.com/v1/contacts/search \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "filter": {    "combinator": "and",    "rules": [      {        "attribute": "contact.custom.plan",        "operator": "eq",        "value": "business"      },      {        "attribute": "contact.last_seen_at",        "operator": "within_last_days",        "value": 30      }    ]  },  "limit": 50}'
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/search", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    filter: {      combinator: "and",      rules: [        {          attribute: "contact.custom.plan",          operator: "eq",          value: "business",        },        {          attribute: "contact.last_seen_at",          operator: "within_last_days",          value: 30,        },      ],    },    limit: 50,  }),})const data = await res.json()
import osimport requests res = requests.post(    "https://api.rabbitblaze.com/v1/contacts/search",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "filter": {            "combinator": "and",            "rules": [                {                    "attribute": "contact.custom.plan",                    "operator": "eq",                    "value": "business",                },                {                    "attribute": "contact.last_seen_at",                    "operator": "within_last_days",                    "value": 30,                },            ],        },        "limit": 50,    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "items": [    {      "object": "contact",      "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",      "role": "user",      "externalId": "usr_48213",      "email": "[email protected]",      "phone": "+49 30 1234567",      "name": "Lena Fischer",      "avatarUrl": null,      "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",      "location": {        "city": "Berlin",        "region": "Berlin",        "country": "Germany",        "countryCode": "DE",        "timezone": "Europe/Berlin"      },      "language": "de",      "browser": "Chrome",      "os": "macOS",      "lastSeenAt": "2026-10-02T13:58:20.000Z",      "lastContactedAt": "2026-10-02T14:11:08.000Z",      "lastRepliedAt": "2026-10-02T14:05:31.000Z",      "signedUpAt": "2025-03-08T10:00:00.000Z",      "sessionCount": 214,      "unsubscribedFromEmails": false,      "blocked": false,      "customAttributes": {        "plan": "business",        "seats": 12,        "mrr": 1490      },      "tags": [        {          "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",          "name": "VIP"        }      ],      "companies": [        {          "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",          "name": "Northwind Analytics"        }      ],      "createdAt": "2026-09-14T09:12:44.000Z",      "updatedAt": "2026-10-02T16:40:03.000Z"    }  ],  "nextCursor": null,  "total": 1}

Retrieve a contact

GET /v1 /contacts/{id} contacts:read

One person by id.

Path parameters

id string required
The contact id.
curl https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f", {  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.get(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Create a contact

POST /v1 /contacts contacts:write

Creates a user (default) or a lead. Users need an email or an externalId; leads need a name, email or phone (and never get an externalId). An email or externalId that already belongs to someone answers 409 conflict — look the person up first and update them instead.

Body

role enum
user (default) or lead.
name string | null
Full name, up to 200 characters.
email string | null
Email address. Must be unique among users.
phone string | null
Phone number, up to 40 characters.
externalId string | null
Your product’s user id, up to 255 characters.
ownerId string | null
A teammate id.
customAttributes object
Values by attribute key (up to 100 at once). Values are checked against each attribute’s type; null clears one.
companyId string | null
Link the person to a company.
tagIds string[]
Up to 20 tag ids.
curl -X POST https://api.rabbitblaze.com/v1/contacts \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "role": "user",  "name": "Lena Fischer",  "email": "[email protected]",  "externalId": "usr_48213",  "companyId": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",  "customAttributes": {    "plan": "business",    "seats": 12  }}'
const res = await fetch("https://api.rabbitblaze.com/v1/contacts", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    role: "user",    name: "Lena Fischer",    email: "[email protected]",    externalId: "usr_48213",    companyId: "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",    customAttributes: {      plan: "business",      seats: 12,    },  }),})const data = await res.json()
import osimport requests res = requests.post(    "https://api.rabbitblaze.com/v1/contacts",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "role": "user",        "name": "Lena Fischer",        "email": "[email protected]",        "externalId": "usr_48213",        "companyId": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",        "customAttributes": {            "plan": "business",            "seats": 12,        },    },)res.raise_for_status()data = res.json()
Response · 201 Created 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Update a contact

PATCH /v1 /contacts/{id} contacts:write

Changes only the fields you send. Send role: "user" to turn a lead into a user. Custom attributes merge into the existing ones.

Path parameters

id string required
The contact id.

Body

name string | null
Full name, up to 200 characters.
email string | null
Email address. Must be unique among users.
phone string | null
Phone number, up to 40 characters.
externalId string | null
Your product’s user id, up to 255 characters.
ownerId string | null
A teammate id.
customAttributes object
Values by attribute key (up to 100 at once). Values are checked against each attribute’s type; null clears one.
avatarUrl string | null
An http(s) image URL.
role "user"
Convert a lead into a user.
signedUpAt timestamp | null
ISO-8601 with a timezone.
unsubscribedFromEmails boolean
Opt out of outbound emails.
blocked boolean
Block the person from starting conversations.
curl -X PATCH https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "name": "Lena Fischer",  "customAttributes": {    "seats": 14  }}'
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f", {  method: "PATCH",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    name: "Lena Fischer",    customAttributes: {      seats: 14,    },  }),})const data = await res.json()
import osimport requests res = requests.patch(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "name": "Lena Fischer",        "customAttributes": {            "seats": 14,        },    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 14,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Delete a contact

DELETE /v1 /contacts/{id} contacts:write

Deletes the person with their conversations, events and notes. This can’t be undone; the deletion is recorded in the audit log.

Path parameters

id string required
The contact id.
curl -X DELETE https://api.rabbitblaze.com/v1/contacts/0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c", {  method: "DELETE",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.delete(    "https://api.rabbitblaze.com/v1/contacts/0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c",  "deleted": true}

Merge a lead into a user

POST /v1 /contacts/merge contacts:write

Moves the lead’s conversations, events, notes, tags and companies onto the user, fills in details the user doesn’t have yet, and deletes the lead — for example after an anonymous visitor signs up. Returns the user.

Body

leadId string required
The lead to merge (deleted afterwards).
userId string required
The user that keeps everything.
curl -X POST https://api.rabbitblaze.com/v1/contacts/merge \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "leadId": "0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c",  "userId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f"}'
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/merge", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    leadId: "0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c",    userId: "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  }),})const data = await res.json()
import osimport requests res = requests.post(    "https://api.rabbitblaze.com/v1/contacts/merge",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "leadId": "0199c513-0d1e-7f2a-8b3c-4d5e6f7a8b9c",        "userId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Tag a contact

POST /v1 /contacts/{id}/tags contacts:write

Adds a tag (fires contact.tag.added). Remove it with DELETE /contacts/{id}/tags/{tagId}. Both return the contact.

Path parameters

id string required
The contact id.

Body

tagId string required
A tag id.
curl -X POST https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/tags \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "tagId": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c"}'
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/tags", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    tagId: "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",  }),})const data = await res.json()
import osimport requests res = requests.post(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/tags",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "tagId": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Remove a tag from a contact

DELETE /v1 /contacts/{id}/tags/{tagId} contacts:write

Removes the tag from the person and returns the contact.

Path parameters

id string required
The contact id.
tagId string required
The tag id.
curl -X DELETE https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/tags/0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/tags/0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c", {  method: "DELETE",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.delete(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/tags/0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Attach a company

POST /v1 /contacts/{id}/companies contacts:write

Links the person to a company (people can belong to several). Detach with DELETE /contacts/{id}/companies/{companyId}. Both return the contact.

Path parameters

id string required
The contact id.

Body

companyId string required
A company id.
curl -X POST https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/companies \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY" \  -H "Content-Type: application/json" \  -d '{  "companyId": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a"}'
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/companies", {  method: "POST",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,    "Content-Type": "application/json",  },  body: JSON.stringify({    companyId: "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",  }),})const data = await res.json()
import osimport requests res = requests.post(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/companies",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    json={        "companyId": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [    {      "id": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "name": "Northwind Analytics"    }  ],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

Detach a company

DELETE /v1 /contacts/{id}/companies/{companyId} contacts:write

Removes the link between the person and the company. Both stay.

Path parameters

id string required
The contact id.
companyId string required
The company id.
curl -X DELETE https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/companies/0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/companies/0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a", {  method: "DELETE",  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.delete(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/companies/0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "object": "contact",  "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",  "role": "user",  "externalId": "usr_48213",  "email": "[email protected]",  "phone": "+49 30 1234567",  "name": "Lena Fischer",  "avatarUrl": null,  "ownerId": "0199a8f2-2d3e-7f4a-9b5c-6d7e8f9a0b1c",  "location": {    "city": "Berlin",    "region": "Berlin",    "country": "Germany",    "countryCode": "DE",    "timezone": "Europe/Berlin"  },  "language": "de",  "browser": "Chrome",  "os": "macOS",  "lastSeenAt": "2026-10-02T13:58:20.000Z",  "lastContactedAt": "2026-10-02T14:11:08.000Z",  "lastRepliedAt": "2026-10-02T14:05:31.000Z",  "signedUpAt": "2025-03-08T10:00:00.000Z",  "sessionCount": 214,  "unsubscribedFromEmails": false,  "blocked": false,  "customAttributes": {    "plan": "business",    "seats": 12,    "mrr": 1490  },  "tags": [    {      "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",      "name": "VIP"    }  ],  "companies": [],  "createdAt": "2026-09-14T09:12:44.000Z",  "updatedAt": "2026-10-02T16:40:03.000Z"}

List a contact’s conversations

GET /v1 /contacts/{id}/conversations conversations:read

Every conversation with this person, newest first.

Path parameters

id string required
The contact id.

Query parameters

limit integer
Items per page, 1–100. Default 25.
cursor string
The nextCursor of the previous page.
curl https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/conversations \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/conversations", {  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.get(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/conversations",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "items": [    {      "object": "conversation",      "id": "0199c520-7e8f-7a9b-8c0d-1e2f3a4b5c6d",      "number": 1042,      "state": "open",      "channel": "messenger",      "subject": null,      "title": "Invoice shows the wrong VAT number",      "isPriority": false,      "contact": {        "id": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",        "name": "Lena Fischer",        "email": "[email protected]",        "role": "user"      },      "companyId": "0199c514-2b3c-7d4e-9f5a-6b7c8d9e0f1a",      "assignee": {        "id": "0199a8f2-3e4f-7a5b-8c6d-7e8f9a0b1c2d",        "name": "Jonas Weber"      },      "team": {        "id": "0199a8f2-4f5a-7b6c-9d7e-8f9a0b1c2d3e",        "name": "Billing"      },      "tags": [        {          "id": "0199a8f3-5d6e-7f7a-8b8c-9d0e1f2a3b4c",          "name": "VIP"        }      ],      "customAttributes": {        "invoice_number": "INV-4412"      },      "waitingSince": null,      "snoozedUntil": null,      "closedAt": null,      "lastMessageAt": "2026-10-02T14:11:08.000Z",      "firstContactMessageAt": "2026-10-02T14:05:31.000Z",      "firstTeammateReplyAt": "2026-10-02T14:11:08.000Z",      "aiAgentState": "handed_off",      "rating": null,      "sla": {        "status": "met",        "dueAt": null      },      "ticket": null,      "messageCount": 4,      "createdAt": "2026-10-02T14:05:31.000Z",      "updatedAt": "2026-10-02T14:11:08.000Z"    }  ],  "nextCursor": null}

List a contact’s events

GET /v1 /contacts/{id}/events events:read

Events tracked for this person, newest first.

Path parameters

id string required
The contact id.

Query parameters

limit integer
Items per page, 1–100. Default 25.
cursor string
The nextCursor of the previous page.
curl https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/events?limit=10 \  -H "Authorization: Bearer $RABBITBLAZE_API_KEY"
const res = await fetch("https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/events?limit=10", {  headers: {    Authorization: `Bearer ${process.env.RABBITBLAZE_API_KEY}`,  },})const data = await res.json()
import osimport requests res = requests.get(    "https://api.rabbitblaze.com/v1/contacts/0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f/events",    headers={"Authorization": f"Bearer {os.environ['RABBITBLAZE_API_KEY']}"},    params={        "limit": "10",    },)res.raise_for_status()data = res.json()
Response · 200 OK 
{  "items": [    {      "object": "event",      "id": "0199c530-3a4b-7c5d-8e6f-7a8b9c0d1e2f",      "name": "invoice-paid",      "contactId": "0199c512-6a7b-7c8d-9e0f-1a2b3c4d5e6f",      "metadata": {        "invoice": "INV-4412",        "amount": 149000,        "currency": "eur"      },      "occurredAt": "2026-10-02T15:20:00.000Z"    }  ],  "nextCursor": "WyIyMDI2LTEwLTAyVDE0OjA1OjMxLjAwMFoiLCIwMTk5YzUyMC03ZThmIl0"}