Provision a new phone line

const url = 'https://saperly.com/api/v1/lines';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"Customer Support Line","mode":"webhook","webhook_url":"https://support.example.com/webhooks/saperly","status_callback_url":"https://support.example.com/status"}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "line": {
    "id": "a3f1c9e2-7b4d-4f8a-9c2e-1d2b3f4a5c6d",
    "phone_number": "+15558675309",
    "display_name": "Customer Support Line",
    "name": "Customer Support Line",
    "mode": "webhook",
    "audio_handler_url": "",
    "webhook_url": "https://support.example.com/webhooks/saperly",
    "status_callback_url": "https://support.example.com/status",
    "compliance_enabled": true,
    "system_prompt": "",
    "begin_message": "",
    "voice": "",
    "context_limit": 10,
    "recording_enabled": true,
    "status": "provisioning",
    "environment": "live",
    "created_at": "2024-01-15T09:30:00Z"
  }
}

Provisions a new US phone number and creates a line with the specified configuration. Costs $2.50/month per number — first number free for 30 days. The phone number is assigned automatically.

Authentication

AuthorizationBearer

Send as Authorization: Bearer <your-key>. Obtain keys from the portal — prefix sk_live_ for production, sk_test_ for sandbox.

Request

This endpoint expects an object.

namestringRequired>=1 character

Human-readable name for the line

modeenumOptional

audio: you handle audio via WebSocket. webhook: you receive transcript webhooks (canonical name). text: legacy alias for webhook — still accepted, normalized server-side. hosted: Saperly AI handles the conversation.

Allowed values:

audio_handler_urlstringOptionalformat: "uri"

WebSocket URL for audio streaming (required for audio mode, must be wss://)

webhook_urlstringOptionalformat: "uri"

HTTPS URL to receive call events (required for webhook mode)

status_callback_urlstringOptionalformat: "uri"

HTTPS URL for call status updates

compliance_enabledbooleanOptionalDefaults to false

Whether to enforce compliance checks (disclosure, consent)

system_promptstringOptional1-4000 characters

System prompt for hosted mode AI conversations

begin_messagestringOptional1-500 characters

First message spoken by the AI when a call connects (hosted mode)

voicestringOptional

ElevenLabs voice ID from GET /v1/voices

context_limitintegerOptional1-50

Number of conversation turns to include as context

recording_enabledbooleanOptionalDefaults to false

Whether to record calls on this line

Response

Line created

lineobject

Errors

401

Unauthorized Error

422

Unprocessable Entity Error

429

Too Many Requests Error