API reference

Authenticates with the Bearer partner key and returns the identity of the partner the key belongs to. It needs no line scope (the delegation gate is not involved), so use it to verify the authentication plumbing.

Creates a line. The response carries no phone number (the number is connected separately). With an Idempotency-Key header, a repeat request with the same key replays the stored first response (no duplicate creation). externalId is your identifier for the line (a mall id, say); creating again with the same value is refused with 409.

Includes the number (null before one is connected), integration status and a plan summary.

Terminates the line. A line that still holds an active number must have it released first; until then termination is held with 502 (CARRIER_RELEASE_FAILED) and the line stays active. Email support@livespeech.ai with the tenantId to release the number. purge: true also removes what the line stored, such as the persona and summary recipients.

Once termination completes, the externalId mapping and the delegation link are released: the same externalId can be used to sign up (create) again, the terminated line no longer counts against the quota, and it disappears from list and read (later access answers 403).

A partial patch that updates only the fields sent. It can take up to 5 minutes for a change to reach live calls.

Call summaries for a delegated line, newest first. Returns summary fields only — no full transcript or recording URL, and the caller's number (callerNumber) is masked to its last four digits. Calls the operator deleted in the console do not appear.

Returns the current configuration. Only the last four characters of the signing secret are included.

Registers (or replaces) the one webhook endpoint per partner. The URL must be https; URLs with credentials and private or loopback hosts are refused (422 WEBHOOK_URL_INVALID). Omitting events subscribes to every supported event; if an unsupported event is included, the whole request is refused with 422 UNKNOWN_EVENT.

The signing secret is returned in full only in this response (signingSecret) — it was issued when the partner account was created, and the registration response is its official hand-over. Later GETs return only a four-character hint.

When a line's call (session) ends and its summary is final, a call.completed event is POSTed to the registered webhook URL. The payload carries tenantId so the partner can route it to the right store. Phone numbers, transcripts and recording URLs are not included.

Delivery guarantee: at least once. The same callId can arrive twice on rare occasions, so the receiver must de-duplicate by callId.

Success and retries: a 2xx response counts as success (the body is ignored; respond within 10 seconds; redirects are not followed and count as failure). 5xx · 408 · 429 · no response (timeout, connection failure, redirect) are retried with exponential backoff (starting at 1 minute, doubling, up to 1 hour apart), for 8 attempts in total including the first. Any other 4xx is taken as the receiver refusing the request: no retry, and that delivery ends.

Signature verification (X-LiveSpeech-Signature):

1. Parse the header: t={unix seconds},v1={hex HMAC}.
2. Drop the whsec_ prefix from the secret and hex-decode it to get the raw key.
3. Sign {t}.{raw request body bytes} with HMAC-SHA256 and compare with v1 in constant time.
4. Reject as a replay if t is more than 5 minutes away from the current time.