Try it uses test keys only. Requests go straight from your browser to https://voice-api.relationsai.com/v1 with a rai_test_ key, which never places a real call. It works once the API is enabled for your workspace (private preview: support@relationsai.com). Your key stays in this tab's memory; live keys are refused.

Phone numbers

Download schema

The workspace's phone numbers and which agents use them. Numbers are added and assigned in the console.

List phone numbers

GET

https://voice-api.relationsai.com/v1

/phone-numbers

Bearer (rai_test_... or rai_live_...)

Lists the workspace's phone numbers and the agents that use them. Numbers are added and assigned in the console. A number is listed only when the workspace has proven it holds that number, so a number visible here can be used as a caller number.

outbound_agent_ids are the agents that call from the number; a call without phone_number_id uses the agent's outbound number. inbound_agent_id answers calls to the number. Listed by number, in a stable order.

GET /v1/phone-numbers · Operation ID: listPhoneNumbers

List phone numbers › query Parameters

limit

integer · min: 1 · max: 100

Maximum number of objects to return, from 1 to 100. Defaults to 25.

Default: 25

cursor

string · minLength: 1 · maxLength: 512

The next_cursor of the previous page. Send it with exactly the same filters as the request that returned it; a changed filter set is 400 invalid_cursor.

List phone numbers › Responses

A page of phone numbers.

PhoneNumberList

object

string · const · required

Always list.

Const value: list

has_more

boolean · required

True when more objects exist after this page.

next_cursor

string | null · required

Pass as cursor (with the same filters) to fetch the next page. Null on the last page.

PhoneNumber[] · required

Phone numbers on this page.

GET/phone-numbers

curl -X GET https://voice-api.relationsai.com/v1/phone-numbers \
     -H "Authorization: Bearer <token>"

Example Responses

{
  "object": "list",
  "data": [
    {
      "id": "pn_6Vhm3sFrB5UpmXAnsvmDu",
      "object": "phone_number",
      "livemode": false,
      "number": "+12025550150",
      "label": "Sample number",
      "status": "active",
      "capabilities": {
        "outbound": true,
        "inbound": false
      },
      "inbound_agent_id": null,
      "outbound_agent_ids": [
        "agent_1ZltiWzxrXmMprGD6q63"
      ],
      "sample": true
    },
    {
      "id": "pn_5Lq8Xc2Rk9TzW3mBv7Np4d",
      "object": "phone_number",
      "livemode": false,
      "number": "+918000000001",
      "label": "Collections line",
      "status": "active",
      "capabilities": {
        "outbound": true,
        "inbound": true
      },
      "inbound_agent_id": null,
      "outbound_agent_ids": [
        "agent_3hT9kQ2mVx7RbN4pLc8Wz1"
      ],
      "sample": false
    }
  ],
  "has_more": false,
  "next_cursor": null
}

json

application/json

Retrieve a phone number

GET

https://voice-api.relationsai.com/v1

/phone-numbers/{phone_number_id}

Bearer (rai_test_... or rai_live_...)

Returns one phone number with its capabilities and agent assignments. There is no carrier or account information in this object.

GET /v1/phone-numbers/{phone_number_id} · Operation ID: getPhoneNumber

Retrieve a phone number › path Parameters

phone_number_id

string · pattern: ^pn_[A-Za-z0-9_-]{1,… · required

The phone number id (pn_...).

Retrieve a phone number › Responses

The phone number.

A phone number your workspace can call from or be called on. Numbers are added and assigned to agents in the console. An outbound call shows the caller number chosen for it; by default that is the number assigned to the agent for outbound calls.

PhoneNumber

id

string · pattern: ^pn_[A-Za-z0-9_-]{1,… · required

Phone number id (pn_...).

object

string · const · required

Always phone_number.

Const value: phone_number

livemode

boolean · required

Mode of the key that read it. Numbers are shared configuration, readable in both modes.

number

string · pattern: ^\+[1-9][0-9]{7,14}$ · required

The number in E.164 format.

label

string | null · required

Label given in the console, if any.

status

string · enum · required

active numbers can be used. pending numbers are still being set up. Open enum.

Enum values:

active

pending

unknown

object · required

What the number supports.

inbound_agent_id

string | null · required

The agent of this workspace that answers calls to this number, if any.

outbound_agent_ids

string[] · required

Agents of this workspace that call from this number.

sample

boolean · required

True only for the built-in sample number that exists in test mode.

Agents Calls