Phone Numbers

Phone numbers route inbound calls to agents. A phone number is claimed by your organization and can be assigned to at most one agent at a time; an agent can have multiple numbers.

Purchasing and claiming numbers happens in the Orbitali dashboard. The public API lists your organization's numbers and manages which agent each number routes to.

All endpoints on this page use API key authentication:

Authorization: Bearer $ORBITALI_API_KEY

Public phone number endpoints

Method	Path	Description
GET	/public/v1/phone-numbers	List phone numbers
GET	/public/v1/agents/{agent_id}/phone-numbers	List an agent's assigned numbers
POST	/public/v1/agents/{agent_id}/phone-numbers	Assign a phone number to an agent
DELETE	/public/v1/agents/{agent_id}/phone-numbers/{phone_number_id}	Unassign a phone number from an agent

List phone numbers

Returns the organization's phone numbers with claim status and current agent assignment. Numbers without assignedAgentId are available to assign.

curl https://api.orbitali.ai/public/v1/phone-numbers \
  -H "Authorization: Bearer $ORBITALI_API_KEY"

Response:

[
  {
    "id": "40000000-0000-4000-8000-000000000001",
    "phoneNumber": "+15550001000",
    "friendlyName": "+15550001000",
    "status": "claimed",
    "source": "managed",
    "provider": "telnyx",
    "setupStatus": "configured",
    "assignedAgentId": "9dbf0d0b-2b55-45de-8c41-7a2d9b0ce8e9",
    "assignedAgentName": "Receptionist",
    "countryCode": "US"
  }
]

status is one of claimed, available, released, or suspended. Only claimed numbers can be assigned to agents.

List an agent's assigned numbers

Returns the phone numbers currently assigned to one agent, including the per-number handoff destination.

curl https://api.orbitali.ai/public/v1/agents/$AGENT_ID/phone-numbers \
  -H "Authorization: Bearer $ORBITALI_API_KEY"

Response:

[
  {
    "phoneNumberId": "40000000-0000-4000-8000-000000000001",
    "phoneNumber": "+15550001000",
    "friendlyName": "+15550001000",
    "handoffPhoneNumber": "+15551234567"
  }
]

Assign a phone number

Assigns a claimed phone number to an agent so it answers calls on that number. If the number is currently assigned to another agent, it moves to the given agent.

curl https://api.orbitali.ai/public/v1/agents/$AGENT_ID/phone-numbers \
  -X POST \
  -H "Authorization: Bearer $ORBITALI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "40000000-0000-4000-8000-000000000001",
    "handoffPhoneNumber": "+15551234567"
  }'

handoffPhoneNumber is optional and sets the handoff destination used by transfer_call for inbound calls on this number.

Response (201):

{
  "phoneNumberId": "40000000-0000-4000-8000-000000000001"
}

Assignments can also be replaced in bulk through the agent update endpoints with phoneNumberAssignments; see the Agents reference.

Unassign a phone number

Removes a phone number assignment from an agent. The number stays claimed by the organization.

curl https://api.orbitali.ai/public/v1/agents/$AGENT_ID/phone-numbers/$PHONE_NUMBER_ID \
  -X DELETE \
  -H "Authorization: Bearer $ORBITALI_API_KEY"

Response:

{
  "phoneNumberId": "40000000-0000-4000-8000-000000000001"
}

Errors

Status	Code	Description
401	—	Missing, malformed, or invalid API key
404	—	Agent does not exist or belongs to another organization
404	PHONE_NUMBER_NOT_FOUND	Phone number does not exist or belongs to another organization
409	PHONE_NUMBER_NOT_CLAIMED	Phone number must be claimed before it can be assigned
409	PHONE_NUMBER_LIMIT_EXCEEDED	The agent already has the maximum of 25 assigned phone numbers
404	— (unassign)	Phone number is not assigned to this agent