Contacts
Every call needs Authorization: Bearer <key>. 16 calls:
- List contacts:
GET /v1/contacts - Create a contact:
POST /v1/contacts - Export contacts as CSV:
GET /v1/contacts/export - Import contacts from CSV:
POST /v1/contacts/import - Get a contact:
GET /v1/contacts/:id - Update a contact:
PATCH /v1/contacts/:id - Delete a contact:
DELETE /v1/contacts/:id - Record a contact's consent:
POST /v1/contacts/:id/consent - Attach or detach a contact's labels:
POST /v1/contacts/:id/labels - Opt a contact out:
POST /v1/contacts/:id/opt-out - List labels:
GET /v1/labels - Create a label:
POST /v1/labels - Rename or recolour a label:
PATCH /v1/labels/:id - List segments with their current contact counts:
GET /v1/segments - Create a segment:
POST /v1/segments - Rename a segment or change its definition:
PATCH /v1/segments/:id
List contacts
GET /v1/contacts
Agents see the contacts they own, contacts in conversations they can see, and unowned contacts with no conversation yet.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | No | From 1 to 100. Default 50. |
cursor | string | No | Opaque cursor from next_cursor. Up to 512 characters. |
q | string | No | Search name, phone, email or company. Up to 100 characters. |
phone | string | No | Phone number in E.164 format. |
label | string | No | Up to 64 characters. |
segment_id | string (uuid) | No | |
consent_status | enum | No | One of: unknown, opted_in, opted_out. |
owner_user_id | string (uuid) | No | |
line_id | string | No | Contacts whose sticky sender is this line. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
data | object[] | |
data[].assigned_line_id | string or null | Line id (ln_...). |
data[].capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
data[].company | string or null | |
data[].consent_at | string (date-time) or null | ISO 8601 timestamp. |
data[].consent_source | string or null | |
data[].consent_status | enum | One of: unknown, opted_in, opted_out. |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].email | string or null | |
data[].fields | object | |
data[].first_name | string or null | |
data[].first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
data[].id | string | Contact id (ctc_...). |
data[].imessage_capable | boolean or null | |
data[].labels | string[] | |
data[].last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
data[].last_name | string or null | |
data[].last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
data[].owner_user_id | string (uuid) or null | |
data[].phone | string | Phone number in E.164 format. |
data[].updated_at | string (date-time) | ISO 8601 timestamp. |
next_cursor | string or null | Pass as cursor to get the next page; null at the end. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Create a contact
POST /v1/contacts
The phone number is normalised to E.164. A number that opted out before is created opted out.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
company | string | No | Up to 200 characters. |
consent_source | string | No | Up to 200 characters. |
consent_status | enum | No | One of: unknown, opted_in. |
email | string (email) | No | Up to 254 characters. |
fields | object | No | Custom fields. |
first_name | string | No | Up to 100 characters. |
labels | string[] | No | Up to 50 items. |
last_name | string | No | Up to 100 characters. |
owner_user_id | string (uuid) | No | |
phone | string | Yes | Phone number. E.164, or a US/Canada number such as (917) 555-0142. Up to 32 characters. |
Response 201
| Field | Type | Description |
|---|---|---|
assigned_line_id | string or null | Line id (ln_...). |
capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
company | string or null | |
consent_at | string (date-time) or null | ISO 8601 timestamp. |
consent_source | string or null | |
consent_status | enum | One of: unknown, opted_in, opted_out. |
created_at | string (date-time) | ISO 8601 timestamp. |
email | string or null | |
fields | object | |
first_name | string or null | |
first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | Contact id (ctc_...). |
imessage_capable | boolean or null | |
labels | string[] | |
last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
last_name | string or null | |
last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
owner_user_id | string (uuid) or null | |
phone | string | Phone number in E.164 format. |
updated_at | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Export contacts as CSV
GET /v1/contacts/export
Streams every matching contact the caller can see. Cells that a spreadsheet would run as a formula are prefixed with an apostrophe.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | enum | No | One of: csv. Default "csv". |
label | string | No | Up to 64 characters. |
segment_id | string (uuid) | No | |
consent_status | enum | No | One of: unknown, opted_in, opted_out. |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
No body.
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Import contacts from CSV
POST /v1/contacts/import
Checks the header and mapping, then queues the import (up to 50000 rows) and returns the job.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
consent_source | string | No | Up to 200 characters. |
csv | string | Yes | Up to 5000000 characters. |
labels | string[] | No | Up to 10 items. |
mapping | object | Yes | |
update_existing | boolean | No | Default false. |
Response 202
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
errors | object[] | |
errors[].message | string | |
errors[].row | integer | From -9007199254740991 to 9007199254740991. |
id | string (uuid) | |
imported | integer | From -9007199254740991 to 9007199254740991. |
skipped | integer | From -9007199254740991 to 9007199254740991. |
status | enum | One of: queued, running, completed, failed. |
total_rows | integer or null | From -9007199254740991 to 9007199254740991. |
updated | integer | From -9007199254740991 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Get a contact
GET /v1/contacts/:id
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact id (ctc_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
assigned_line_id | string or null | Line id (ln_...). |
capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
company | string or null | |
consent_at | string (date-time) or null | ISO 8601 timestamp. |
consent_source | string or null | |
consent_status | enum | One of: unknown, opted_in, opted_out. |
created_at | string (date-time) | ISO 8601 timestamp. |
email | string or null | |
fields | object | |
first_name | string or null | |
first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | Contact id (ctc_...). |
imessage_capable | boolean or null | |
labels | string[] | |
last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
last_name | string or null | |
last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
owner_user_id | string (uuid) or null | |
phone | string | Phone number in E.164 format. |
updated_at | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Update a contact
PATCH /v1/contacts/:id
labels and fields replace the current values. Consent changes go through the consent and opt-out routes, except that moving a contact to a number that opted out before makes it opted out.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact id (ctc_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
company | string or null | No | Up to 200 characters. |
email | string (email) or null | No | Up to 254 characters. |
fields | object | No | Custom fields. |
first_name | string or null | No | Up to 100 characters. |
labels | string[] | No | Up to 50 items. |
last_name | string or null | No | Up to 100 characters. |
owner_user_id | string (uuid) or null | No | |
phone | string | No | Phone number. E.164, or a US/Canada number such as (917) 555-0142. Up to 32 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
assigned_line_id | string or null | Line id (ln_...). |
capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
company | string or null | |
consent_at | string (date-time) or null | ISO 8601 timestamp. |
consent_source | string or null | |
consent_status | enum | One of: unknown, opted_in, opted_out. |
created_at | string (date-time) | ISO 8601 timestamp. |
email | string or null | |
fields | object | |
first_name | string or null | |
first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | Contact id (ctc_...). |
imessage_capable | boolean or null | |
labels | string[] | |
last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
last_name | string or null | |
last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
owner_user_id | string (uuid) or null | |
phone | string | Phone number in E.164 format. |
updated_at | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Delete a contact
DELETE /v1/contacts/:id
Deletes the contact with its conversations, messages and notes. Opt-out records are kept, so the number stays opted out if it is added again.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact id (ctc_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
deleted | enum | One of: true. |
id | string | Contact id (ctc_...). |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Record a contact's consent
POST /v1/contacts/:id/consent
opted_in records where consent came from. opted_out works like opt-out.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact id (ctc_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
source | string | Yes | Where consent came from, e.g. web_form. Up to 200 characters. |
status | enum | Yes | One of: unknown, opted_in, opted_out. |
Response 200
| Field | Type | Description |
|---|---|---|
assigned_line_id | string or null | Line id (ln_...). |
capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
company | string or null | |
consent_at | string (date-time) or null | ISO 8601 timestamp. |
consent_source | string or null | |
consent_status | enum | One of: unknown, opted_in, opted_out. |
created_at | string (date-time) | ISO 8601 timestamp. |
email | string or null | |
fields | object | |
first_name | string or null | |
first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | Contact id (ctc_...). |
imessage_capable | boolean or null | |
labels | string[] | |
last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
last_name | string or null | |
last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
owner_user_id | string (uuid) or null | |
phone | string | Phone number in E.164 format. |
updated_at | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Attach or detach a contact's labels
POST /v1/contacts/:id/labels
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact id (ctc_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
add | string[] | No | Up to 50 items. |
remove | string[] | No | Up to 50 items. |
Response 200
| Field | Type | Description |
|---|---|---|
assigned_line_id | string or null | Line id (ln_...). |
capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
company | string or null | |
consent_at | string (date-time) or null | ISO 8601 timestamp. |
consent_source | string or null | |
consent_status | enum | One of: unknown, opted_in, opted_out. |
created_at | string (date-time) | ISO 8601 timestamp. |
email | string or null | |
fields | object | |
first_name | string or null | |
first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | Contact id (ctc_...). |
imessage_capable | boolean or null | |
labels | string[] | |
last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
last_name | string or null | |
last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
owner_user_id | string (uuid) or null | |
phone | string | Phone number in E.164 format. |
updated_at | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Opt a contact out
POST /v1/contacts/:id/opt-out
Stops all sending to the contact on every channel and records the opt-out.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Contact id (ctc_...). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
keyword | string | No | Up to 40 characters. |
source | string | Yes | Up to 200 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
assigned_line_id | string or null | Line id (ln_...). |
capability_checked_at | string (date-time) or null | ISO 8601 timestamp. |
company | string or null | |
consent_at | string (date-time) or null | ISO 8601 timestamp. |
consent_source | string or null | |
consent_status | enum | One of: unknown, opted_in, opted_out. |
created_at | string (date-time) | ISO 8601 timestamp. |
email | string or null | |
fields | object | |
first_name | string or null | |
first_reply_at | string (date-time) or null | ISO 8601 timestamp. |
id | string | Contact id (ctc_...). |
imessage_capable | boolean or null | |
labels | string[] | |
last_inbound_at | string (date-time) or null | ISO 8601 timestamp. |
last_name | string or null | |
last_outbound_at | string (date-time) or null | ISO 8601 timestamp. |
owner_user_id | string (uuid) or null | |
phone | string | Phone number in E.164 format. |
updated_at | string (date-time) | ISO 8601 timestamp. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
List labels
GET /v1/labels
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
data | object[] | |
data[].color | string or null | |
data[].contact_count | integer | From 0 to 9007199254740991. |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].id | string (uuid) | |
data[].name | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Create a label
POST /v1/labels
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
color | string | No | |
name | string | Yes | Up to 64 characters. |
Response 201
| Field | Type | Description |
|---|---|---|
color | string or null | |
contact_count | integer | From 0 to 9007199254740991. |
created_at | string (date-time) | ISO 8601 timestamp. |
id | string (uuid) | |
name | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Rename or recolour a label
PATCH /v1/labels/:id
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
color | string or null | No | |
name | string | No | Up to 64 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
color | string or null | |
contact_count | integer | From 0 to 9007199254740991. |
created_at | string (date-time) | ISO 8601 timestamp. |
id | string (uuid) | |
name | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
List segments with their current contact counts
GET /v1/segments
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
data | object[] | |
data[].contact_count | integer or null | From 0 to 9007199254740991. |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].definition | any | |
data[].id | string (uuid) | |
data[].name | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Create a segment
POST /v1/segments
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
definition | any | Yes | |
name | string | Yes | Up to 80 characters. |
Response 201
| Field | Type | Description |
|---|---|---|
contact_count | integer or null | From 0 to 9007199254740991. |
created_at | string (date-time) | ISO 8601 timestamp. |
definition | any | |
id | string (uuid) | |
name | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Rename a segment or change its definition
PATCH /v1/segments/:id
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | Yes |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
definition | any | No | |
name | string | No | Up to 80 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
contact_count | integer or null | From 0 to 9007199254740991. |
created_at | string (date-time) | ISO 8601 timestamp. |
definition | any | |
id | string (uuid) | |
name | string |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.