Line Provisioning

Credential-based line purchasing is available only for inbound_only / Agent plan accounts. It provisions inbound-only phone lines. No dashboard, no checkout redirect: just API calls using your existing API key and secret.

Deprecated: The previous ticket-based POST /accounts/lines/add-line and GET /accounts/lines/line-request/:lineRequestTicketId flows have been deprecated for direct line purchases. Use the preview and confirm endpoints below for API line provisioning.

Endpoints

API line provisioning uses a two-step flow. Preview validates inbound_only / Agent plan eligibility and issues a short-lived token. Confirm consumes that token, charges the card on file, and provisions the new inbound-only line.

Step 1: Preview

Validate that the account is eligible and a line is currently available. The response includes a preview_token that is valid for 10 minutes.

POST /accounts/lines/provision-preview

Example Request

curl -X POST "https://api.sendblue.com/accounts/lines/provision-preview" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET"

Success Response (200)

{
  "status": "OK",
  "preview_token": "lpv_abc123...",
  "expires_at": "2026-05-18T14:30:00.000Z",
  "message": "Call the confirm endpoint with this token within 10 minutes to complete the purchase."
}

Field	Type	Description
status	string	OK
preview_token	string	Single-use token for the confirm step
expires_at	string	ISO 8601 expiration timestamp
message	string	Human-readable next step

Step 2: Confirm

Consume the preview_token, charge the card on file, and provision the line.

POST /accounts/lines/provision-confirm

Request Body

Parameter	Type	Required	Description
preview_token	string	Yes	Token returned by POST /accounts/lines/provision-preview

Example Request

curl -X POST "https://api.sendblue.com/accounts/lines/provision-confirm" \
  -H "sb-api-key-id: YOUR_API_KEY" \
  -H "sb-api-secret-key: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "preview_token": "lpv_abc123..."
  }'

Success Response (200)

{
  "status": "OK",
  "phone_number": "+14155551234",
  "worker_id": "worker_abc123",
  "subscription_id": "sub_abc123"
}

Field	Type	Description
status	string	OK
phone_number	string	The newly provisioned Sendblue phone number
worker_id	string	Internal worker ID for the new line
subscription_id	string	Stripe subscription ID for the line

Rate Limits

Provisioning limits are visible with GET /accounts/limits.

Window	Default	Override
Daily, rolling 24 hours	3 lines	Set limits.api_provision_daily on the account in Firestore
Monthly, rolling 30 days	10 lines	Set limits.api_provision_monthly on the account in Firestore

Limits are checked during both preview and confirm.

Error Responses

{
  "status": "ERROR",
  "error": "daily_limit_reached",
  "message": "Maximum 3 lines can be added per day via API"
}

HTTP Status	Error	Description
400	-	preview_token is missing from confirm
401	-	Invalid API credentials
402	no_card_on_file	No card is available for the account
403	-	Account is not on the inbound_only / Agent plan, or token belongs to another account
410	token_expired	Token expired or was already used
429	daily_limit_reached	Daily provisioning limit reached
429	monthly_limit_reached	Monthly provisioning limit reached
503	no_lines_available	No lines are currently available
500	provisioning_failed	Subscription was created, but line provisioning failed

Notes

• The account must be on the inbound_only / Agent plan; other plans receive a 403.
• Provisioned lines are inbound-only lines.
• A card on file is required; accounts without a card receive a 402.
• Preview tokens are single-use. If confirm fails for any reason, call preview again.
• Both endpoints use standard API key and secret authentication.