Inbound SIP API
Manage inbound SIP connections and numbers when the gateway is enabled.
These endpoints are available only when your Orbitali operator enables the SIP gateway. They use the same organization API key as the rest of the public API. Every route returns 404 when SIP is disabled. Read Inbound SIP for provider configuration and supported audio/transport settings.
Endpoints
| Method | Path | Success |
|---|---|---|
| GET | /public/v1/telephony/sip/connections | 200, array of connections |
| POST | /public/v1/telephony/sip/connections | 201, { connection, password? } |
| PUT | /public/v1/telephony/sip/connections/{connection_id} | 200, { connection, password? } |
| POST | /public/v1/telephony/sip/connections/{connection_id}/rotate | 200, { connection, password } |
| DELETE | /public/v1/telephony/sip/connections/{connection_id} | 200, { id } |
| POST | /public/v1/telephony/sip/numbers | 201, { id } |
Create a connection
curl --fail-with-body https://api.orbitali.ai/public/v1/telephony/sip/connections \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"displayLabel": "Office inbound",
"authMode": "credentials",
"sourceCidrs": [],
"enabled": true
}'
| Field | Requirement |
|---|---|
displayLabel | Required, 1–80 characters |
authMode | Required, credentials or ip |
sourceCidrs | Defaults to []; at most 32 IPv4 addresses/CIDRs. Must be empty for credentials, nonempty for IP authentication. |
enabled | Defaults to true |
outbound | Optional outbound route for handoff; omitted preserves an existing route, null removes it and its password. |
Unknown input fields are rejected. For IP authentication, use authMode: "ip" and your provider's source ranges. Allowlists cannot overlap another connection, including disabled connections.
The response's connection contains id, displayLabel, authMode, sourceCidrs, enabled, username, destination, revision, provisioningStatus, verifiedAt, and outbound (without its password). Store the returned ID as SIP_CONNECTION_ID for later requests. Credential-mode passwords are returned only when generated; store the password securely and configure it at your provider.
List and check provisioning
curl --fail-with-body https://api.orbitali.ai/public/v1/telephony/sip/connections \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Returns an array of connection objects without passwords. provisioningStatus is pending, applied, or failed. applied confirms gateway configuration loading; a non-null verifiedAt records a successful call verification. Test speech, interruption, and hangup after configuration changes.
Replace, disable, or rotate
To update a connection, PUT the complete connection input to /public/v1/telephony/sip/connections/{connection_id}. Include enabled: false to disable it. Changing authentication mode generates new credentials when switching to credential mode.
Rotate a credential-mode password without a request body:
curl --fail-with-body "https://api.orbitali.ai/public/v1/telephony/sip/connections/$SIP_CONNECTION_ID/rotate" \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY"
Store the returned password, update your provider, and wait for the new revision to be applied. IP-mode connections have no password to rotate.
Add and assign a number
curl --fail-with-body https://api.orbitali.ai/public/v1/telephony/sip/numbers \
-X POST \
-H "Authorization: Bearer $ORBITALI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "00000000-0000-4000-8000-000000000001",
"phoneNumber": "+34910000001",
"friendlyName": "Office"
}'
Replace connectionId with your returned UUID and phoneNumber with your provider-routed E.164 number. Both fields are required; friendlyName is optional (1–80 characters). Success returns the new phone-number id. Assign it using Assign a phone number and activate the agent.
Routing requires the authenticated connection and called number together. Unknown or unassigned destinations are rejected before answering. SIP supports incoming calls and direct transfers through an explicitly configured outbound route. REGISTER, SIP extensions, attended transfers, and standalone outbound SIP calls are not supported.
Configure direct call transfers
Set the agent's existing E.164 handoff number, then include outbound in the connection's POST/PUT input:
{
"displayLabel": "Office inbound",
"authMode": "credentials",
"sourceCidrs": [],
"enabled": true,
"outbound": {
"host": "pbx.example.com",
"port": 5060,
"transport": "tcp",
"username": "outbound-user",
"password": "REPLACE_LOCALLY",
"callerId": "+34910000002"
}
}
host is a hostname or IPv4 address, without scheme, path or SIP user. port defaults to 5060 (1–65535); transport is udp (default) or tcp. callerId is a required E.164 number your PBX permits you to present. Original caller identity is not forwarded automatically. Leave username empty for an IP-authorized trunk. Otherwise provide separate outbound credentials; the inbound Orbitali credentials do not authorize calls through your PBX.
Usernames accept letters, digits and _.@+- (at most 128 characters). Passwords accept letters, digits and ._~!$%&*+/@=- (1–128 characters); configuration delimiters and line breaks are rejected. Passwords are encrypted at rest, are never returned by public reads, and are preserved when omitted on update. Sending outbound: null removes the outbound password. Rotating the inbound password preserves the outbound route and its independent password.
Wait for provisioningStatus: "applied", then place a new inbound call. The runtime enables transfer_call only for a configured and applied outbound route with a handoff number. Asterisk waits up to 30 seconds for an answer. Busy, rejection, timeout and connection failures retain the agent conversation; failure to restore audio terminates the call instead of leaving it stranded. On answer, the AI channel is removed and the caller and human remain bridged by Asterisk. The AI session and its usage end at handoff; the human conversation is not recorded or transcribed by the agent. Either party hanging up releases both legs.
The PBX/trunk must authorize outbound calls from the gateway. Asterisk remains in the media path; losing the gateway or ARI control drops active calls. Test the actual PBX before enabling production transfers. Successful configuration loading does not certify outbound routing, caller-ID acceptance, or interoperability.
Delete a connection
curl --fail-with-body "https://api.orbitali.ai/public/v1/telephony/sip/connections/$SIP_CONNECTION_ID" \
-X DELETE \
-H "Authorization: Bearer $ORBITALI_API_KEY"
This deletes the connection and its linked SIP numbers. Disable the connection instead if you want to retain its configuration.
Errors
| Status | Code | Meaning |
|---|---|---|
400 | — | Invalid input, unknown fields, invalid UUID, or missing allowlist |
400 | SIP_OUTBOUND_PASSWORD_REQUIRED | Outbound authentication has a username but no saved or supplied password |
400 | SIP_INVALID_ALLOWLIST | Use valid IPv4 addresses or CIDR prefixes |
401 | UNAUTHORIZED | Missing or invalid API key |
404 | — | SIP is disabled |
404 | SIP_NOT_FOUND | Connection absent or outside the key's organization |
409 | SIP_ALLOWLIST_OVERLAP | Source range overlaps another connection |
409 | SIP_NO_CREDENTIALS | Password rotation requested for an IP connection |
409 | PHONE_NUMBER_EXISTS | Number already exists on this connection |
Adding a number also checks the account's phone-number allowance. Reuse an existing number or adjust the plan if the allowance is exhausted.