Phone Numbers
Manage tenant numbers, Retell provisioning, carrier SIP header mappings, and outbound calls.
List phone numbers and SIP users
List phone numbers and SIP users
Create a phone number or SIP user
Create a phone number or SIP user
Get phone number details
Get phone number details
Update a phone number or SIP user
Update a phone number or SIP user
Delete a phone number
Delete a phone number
Capture the SIP headers of the next inbound test call
Opens a 120-second window. The next inbound INVITE to this number is recorded and rejected with 486 Busy instead of reaching Retell, so its exact headers can be inspected. Poll GET .../sip-header-capture/{sessionId} for the result; raw values expire after 10 minutes and are never stored with mappings. Not needed for forward-all.
Get a SIP header capture
Returns unredacted values for the authenticated tenant's own test call. Responses use Cache-Control: no-store and the transient capture expires automatically.
Cancel a SIP header capture
Cancel a SIP header capture
Get carrier SIP header mappings
Returns the saved header-name rules for the number: plain inbound/bidirectional mappings, derived rules with their transform, and the optional forward-all (passthrough) entry. Captured header values are never stored here.
Replace carrier SIP header mappings
Replaces every SIP header mapping for the number. Up to 10 entries, counting one forward-all entry and each derived rule. Forward-all (direction passthrough, providerHeader '*') is the fastest option: the SIP edge copies eligible carrier headers as ‹prefix›‹Header› plus From/To name, user, and host with no lookup. Plain inbound and bidirectional mappings are also applied on the edge without a lookup. Derived mappings add one internal lookup during call setup and are omitted, not rejected, if that lookup fails. Changes apply to the next inbound call. captureSessionId, when supplied, deletes that transient capture after saving.
Draft a derived SIP header rule with Composer AI
Turns a plain-language instruction into a validated SipHeaderTransform. Uses the platform SIP AI provider chain when enabled and falls back to a built-in interpreter. Only the instruction, header names, and the supplied sampleValue are sent to the model. The draft is not saved; persist it with PUT sip-header-mappings.
Inspect assigned Retell transfer functions and REFER controls
Preview-only discovery. Resolves the exact assigned agent and response-engine versions and returns every transfer function without mutating Retell.
Update Retell transfer headers and REFER controls
Updates only selected functions. Managed PSTN modes require an active entitlement and tenant-owned verified destination ID. Published agents are forked to writable draft versions, patched, published, and reassigned to the phone number before success is returned.
Queue Retell import/provisioning for a phone number or SIP user
Queue Retell import/provisioning for a phone number or SIP user
Queue Retell update/sync for a phone number or SIP user
Queue Retell update/sync for a phone number or SIP user
Rotate Retell-facing SIP digest credentials
Rotate Retell-facing SIP digest credentials
Place an outbound Retell call from this number
Durably queues a Retell outbound call in tenant FIFO order. Dispatch waits until both Retell workspace capacity and the configured SIP-device pool have a slot. The path phone number is the From identity.
Get outbound call request status
Returns FIFO position and capacity state while queued, or the Retell call result after submission. Status is tenant isolated.
Get inbound destination routing
Returns the current inbound destination and non-secret same-tenant registered connections. Requires tenant read access. The browser portal uses this same tenant-scoped route.
Update inbound destination routing
Replaces the phone number's inbound destination. Requires tenant configure access. This changes signaling routing only; it does not import/update Retell or change provider registration.