Lines
Every call needs Authorization: Bearer <key>. 10 calls:
- The workspace's line requests:
GET /v1/line-requests - Request more lines:
POST /v1/line-requests - List the workspace's lines:
GET /v1/lines - Get a line:
GET /v1/lines/:id - Change a line's display name, contact card or pool:
PATCH /v1/lines/:id - Pause a line:
POST /v1/lines/:id/pause - Resume a line you paused:
POST /v1/lines/:id/resume - List line pools:
GET /v1/pools - Create a pool:
POST /v1/pools - Change a pool's name, rotation or SMS fallback:
PATCH /v1/pools/:id
The workspace's line requests
GET /v1/line-requests
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. |
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[].area_codes | string[] | |
data[].count | integer | From 1 to 9007199254740991. |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].id | string (uuid) | |
data[].note | string or null | |
data[].pool_id | string or null | Pool id (pool_...). |
data[].status | enum | One of: pending, in_progress, fulfilled, cancelled. |
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.
Request more lines
POST /v1/line-requests
Creates a request for the bubbl3 team, who provision the lines. A workspace can have at most 5 open (pending or in-progress) requests; another returns 409.
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 |
|---|---|---|---|
area_codes | string[] | No | Up to 10 items. |
count | integer | Yes | From 1 to 50. |
note | string | No | Up to 1000 characters. |
pool_id | string | No | Pool id (pool_...). |
Response 201
| Field | Type | Description |
|---|---|---|
area_codes | string[] | |
count | integer | From 1 to 9007199254740991. |
created_at | string (date-time) | ISO 8601 timestamp. |
id | string (uuid) | |
note | string or null | |
pool_id | string or null | Pool id (pool_...). |
status | enum | One of: pending, in_progress, fulfilled, cancelled. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
List the workspace's lines
GET /v1/lines
State, health, warm-up and today’s usage against the daily caps.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
pool_id | string | No | Pool id (pool_...). |
state | enum | No | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
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_card | object | |
data[].contact_card.image_url | string | Up to 2048 characters. |
data[].contact_card.name | string | Up to 100 characters. |
data[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].daily_new_cap | integer | From 0 to 9007199254740991. |
data[].display_name | string or null | |
data[].health_score | integer | From 0 to 100. |
data[].id | string | Line id (ln_...). |
data[].is_sandbox | boolean | |
data[].phone | string | Phone number in E.164 format. |
data[].pool_id | string or null | Pool id (pool_...). |
data[].state | enum | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
data[].state_changed_at | string (date-time) or null | ISO 8601 timestamp. |
data[].state_reason | string or null | |
data[].usage_today | object | |
data[].usage_today.day | string (date) | Usage day in America/New_York, rolling over at 3 AM. |
data[].usage_today.new_contacts | integer | From 0 to 9007199254740991. |
data[].usage_today.new_contacts_cap | integer | From 0 to 9007199254740991. |
data[].usage_today.sends | integer | From 0 to 9007199254740991. |
data[].usage_today.sends_cap | integer | From 0 to 9007199254740991. |
data[].warmup_day | integer | From 0 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Get a line
GET /v1/lines/:id
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Line id (ln_...). |
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 |
|---|---|---|
contact_card | object | |
contact_card.image_url | string | Up to 2048 characters. |
contact_card.name | string | Up to 100 characters. |
created_at | string (date-time) | ISO 8601 timestamp. |
daily_new_cap | integer | From 0 to 9007199254740991. |
display_name | string or null | |
health_score | integer | From 0 to 100. |
id | string | Line id (ln_...). |
is_sandbox | boolean | |
phone | string | Phone number in E.164 format. |
pool_id | string or null | Pool id (pool_...). |
state | enum | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
state_changed_at | string (date-time) or null | ISO 8601 timestamp. |
state_reason | string or null | |
usage_today | object | |
usage_today.day | string (date) | Usage day in America/New_York, rolling over at 3 AM. |
usage_today.new_contacts | integer | From 0 to 9007199254740991. |
usage_today.new_contacts_cap | integer | From 0 to 9007199254740991. |
usage_today.sends | integer | From 0 to 9007199254740991. |
usage_today.sends_cap | integer | From 0 to 9007199254740991. |
warmup_day | integer | From 0 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Change a line's display name, contact card or pool
PATCH /v1/lines/:id
contact_card fields are merged into the current card.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Line id (ln_...). |
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 |
|---|---|---|---|
contact_card | object | No | |
contact_card.image_url | string (uri) | No | HTTPS URL. Up to 2048 characters. |
contact_card.name | string | No | Up to 100 characters. |
display_name | string or null | No | Up to 80 characters. |
pool_id | string or null | No | Pool id (pool_...). |
Response 200
| Field | Type | Description |
|---|---|---|
contact_card | object | |
contact_card.image_url | string | Up to 2048 characters. |
contact_card.name | string | Up to 100 characters. |
created_at | string (date-time) | ISO 8601 timestamp. |
daily_new_cap | integer | From 0 to 9007199254740991. |
display_name | string or null | |
health_score | integer | From 0 to 100. |
id | string | Line id (ln_...). |
is_sandbox | boolean | |
phone | string | Phone number in E.164 format. |
pool_id | string or null | Pool id (pool_...). |
state | enum | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
state_changed_at | string (date-time) or null | ISO 8601 timestamp. |
state_reason | string or null | |
usage_today | object | |
usage_today.day | string (date) | Usage day in America/New_York, rolling over at 3 AM. |
usage_today.new_contacts | integer | From 0 to 9007199254740991. |
usage_today.new_contacts_cap | integer | From 0 to 9007199254740991. |
usage_today.sends | integer | From 0 to 9007199254740991. |
usage_today.sends_cap | integer | From 0 to 9007199254740991. |
warmup_day | integer | From 0 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Pause a line
POST /v1/lines/:id/pause
Stops sending from a warming, active or throttled line.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Line id (ln_...). |
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 |
|---|---|---|---|
reason | string | No | Up to 500 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
contact_card | object | |
contact_card.image_url | string | Up to 2048 characters. |
contact_card.name | string | Up to 100 characters. |
created_at | string (date-time) | ISO 8601 timestamp. |
daily_new_cap | integer | From 0 to 9007199254740991. |
display_name | string or null | |
health_score | integer | From 0 to 100. |
id | string | Line id (ln_...). |
is_sandbox | boolean | |
phone | string | Phone number in E.164 format. |
pool_id | string or null | Pool id (pool_...). |
state | enum | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
state_changed_at | string (date-time) or null | ISO 8601 timestamp. |
state_reason | string or null | |
usage_today | object | |
usage_today.day | string (date) | Usage day in America/New_York, rolling over at 3 AM. |
usage_today.new_contacts | integer | From 0 to 9007199254740991. |
usage_today.new_contacts_cap | integer | From 0 to 9007199254740991. |
usage_today.sends | integer | From 0 to 9007199254740991. |
usage_today.sends_cap | integer | From 0 to 9007199254740991. |
warmup_day | integer | From 0 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Resume a line you paused
POST /v1/lines/:id/resume
Resumes a line paused from the dashboard or API, back to the state it was paused from (warming, active or throttled). Lines the platform paused stay paused.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Line id (ln_...). |
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 |
|---|---|---|---|
reason | string | No | Up to 500 characters. |
Response 200
| Field | Type | Description |
|---|---|---|
contact_card | object | |
contact_card.image_url | string | Up to 2048 characters. |
contact_card.name | string | Up to 100 characters. |
created_at | string (date-time) | ISO 8601 timestamp. |
daily_new_cap | integer | From 0 to 9007199254740991. |
display_name | string or null | |
health_score | integer | From 0 to 100. |
id | string | Line id (ln_...). |
is_sandbox | boolean | |
phone | string | Phone number in E.164 format. |
pool_id | string or null | Pool id (pool_...). |
state | enum | One of: provisioning, ready, warming, active, throttled, paused, quarantined, retired. |
state_changed_at | string (date-time) or null | ISO 8601 timestamp. |
state_reason | string or null | |
usage_today | object | |
usage_today.day | string (date) | Usage day in America/New_York, rolling over at 3 AM. |
usage_today.new_contacts | integer | From 0 to 9007199254740991. |
usage_today.new_contacts_cap | integer | From 0 to 9007199254740991. |
usage_today.sends | integer | From 0 to 9007199254740991. |
usage_today.sends_cap | integer | From 0 to 9007199254740991. |
warmup_day | integer | From 0 to 9007199254740991. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
List line pools
GET /v1/pools
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[].created_at | string (date-time) | ISO 8601 timestamp. |
data[].fallback_sms | boolean | Deprecated. true unless fallback_sms_mode is off. |
data[].fallback_sms_mode | enum | off: never use SMS. not_imessage: SMS when the contact is not on iMessage. not_imessage_or_failed: also after an iMessage send fails. SMS also needs an active, verified, compliance-confirmed SMS connection. One of: off, not_imessage, not_imessage_or_failed. |
data[].id | string | Pool id (pool_...). |
data[].line_count | integer | From 0 to 9007199254740991. |
data[].name | string | |
data[].rotation | enum | One of: sticky, round_robin. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Create a pool
POST /v1/pools
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 |
|---|---|---|---|
fallback_sms | boolean | No | Deprecated. Use fallback_sms_mode. true maps to not_imessage, false to off. |
fallback_sms_mode | enum | No | off: never use SMS. not_imessage: SMS when the contact is not on iMessage. not_imessage_or_failed: also after an iMessage send fails. SMS also needs an active, verified, compliance-confirmed SMS connection. One of: off, not_imessage, not_imessage_or_failed. |
name | string | Yes | Up to 80 characters. |
rotation | enum | No | One of: sticky, round_robin. Default "sticky". |
Response 201
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
fallback_sms | boolean | Deprecated. true unless fallback_sms_mode is off. |
fallback_sms_mode | enum | off: never use SMS. not_imessage: SMS when the contact is not on iMessage. not_imessage_or_failed: also after an iMessage send fails. SMS also needs an active, verified, compliance-confirmed SMS connection. One of: off, not_imessage, not_imessage_or_failed. |
id | string | Pool id (pool_...). |
line_count | integer | From 0 to 9007199254740991. |
name | string | |
rotation | enum | One of: sticky, round_robin. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Change a pool's name, rotation or SMS fallback
PATCH /v1/pools/:id
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Pool id (pool_...). |
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 |
|---|---|---|---|
fallback_sms | boolean | No | Deprecated. Use fallback_sms_mode. true maps to not_imessage, false to off. |
fallback_sms_mode | enum | No | off: never use SMS. not_imessage: SMS when the contact is not on iMessage. not_imessage_or_failed: also after an iMessage send fails. SMS also needs an active, verified, compliance-confirmed SMS connection. One of: off, not_imessage, not_imessage_or_failed. |
name | string | No | Up to 80 characters. |
rotation | enum | No | One of: sticky, round_robin. |
Response 200
| Field | Type | Description |
|---|---|---|
created_at | string (date-time) | ISO 8601 timestamp. |
fallback_sms | boolean | Deprecated. true unless fallback_sms_mode is off. |
fallback_sms_mode | enum | off: never use SMS. not_imessage: SMS when the contact is not on iMessage. not_imessage_or_failed: also after an iMessage send fails. SMS also needs an active, verified, compliance-confirmed SMS connection. One of: off, not_imessage, not_imessage_or_failed. |
id | string | Pool id (pool_...). |
line_count | integer | From 0 to 9007199254740991. |
name | string | |
rotation | enum | One of: sticky, round_robin. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.