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, paused because its sends went unconfirmed or showed no delivery receipts, or released from quarantine by bubbl3, back to the state it was paused from (warming, active or throttled). Lines the platform paused for anything else 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.