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://myapp.com/webhooks/saperly","status_callback_url":"https://myapp.com/status"}'
};
try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

{
  "line": {
    "id": "string",
    "phone_number": "+15551234567",
    "display_name": "string",
    "name": "string",
    "mode": "audio",
    "audio_handler_url": "string",
    "webhook_url": "string",
    "status_callback_url": "string",
    "compliance_enabled": true,
    "system_prompt": "string",
    "begin_message": "string",
    "voice": "string",
    "context_limit": 1,
    "recording_enabled": true,
    "language": "multi",
    "endpointing_ms": 1,
    "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.

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

Saperly voice slug from GET /v1/voices (e.g. “aria”, “hebrew-warm”)

context_limitintegerOptional1-50

Number of conversation turns to include as context

recording_enabledbooleanOptionalDefaults to false

Whether to record calls on this line

languageenumOptionalDefaults to multi

v0.5.10. Pin the Deepgram speech-to-text language for incoming callers. Defaults to multi (auto-detect per fragment). Pin to a specific code to dramatically improve accuracy on non-English callers — Deepgram’s nova-3 multilingual auto-detect can transcribe Hebrew as Hindi or Spanish as Italian; pinning fixes that. Not supported on hosted-mode lines — Saperly handles language automatically on hosted lines.

endpointing_msinteger or nullOptional100-2000

v0.5.10. Advanced. Override the Deepgram endpointing window for this line (the silence duration after the caller stops speaking before the transcript is finalized). Default: ~700ms platform-wide. Most customers should leave this null. Lower values produce snappier turn-taking; higher values produce cleaner transcripts for slow speakers. Not supported on hosted-mode lines.

Response

Line created

lineobject

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

422

Unprocessable Entity Error

429

Too Many Requests Error