Main Numbers

A main number is a customer-facing phone number on your Phone.inc account — the one you'd publish on a website or business card. Every call and voicemail belongs to exactly one main number. Beyond listing them, you can retrieve the full settings (routing, opening hours) and update them through the API.

The main number model

Each main number has a stable public id, the human label your team uses to identify it (name), the underlying phone number, and its full routing configuration.

Properties

Name
id
Type
string
Description
Unique identifier for the main number.
Name
name
Type
string
Description
The label your team set for this number, like Sales or Support. ASCII letters, numbers, spaces, and -_~!.+ only, up to 128 characters (no accented characters).
Name
number
Type
string
Description
The phone number in E.164 format, e.g. +14155551234.
Name
number_formatted
Type
string
Description
The same number formatted for display, e.g. +1 415-555-1234.
Name
timezone
Type
string
Description
IANA timezone for the main number, e.g. Copenhagen or London.
Name
language
Type
string
Description
Language code used for automated messages, e.g. da or en.
Name
recording_enabled
Type
boolean
Description
Whether calls to this number are recorded.
Name
incoming_call_config
Type
object
Description
The routing configuration for incoming calls. Contains a type field plus type-specific attributes.
Name
outside_opening_hours_config
Type
object | null
Description
The routing configuration used outside opening hours, or null if not set (falls back to incoming call config).
Name
no_answer_config
Type
object | null
Description
The routing configuration that runs when a call is transferred to employees but nobody answers within the ring timer, or null if no fallback is set. Same shape as the other two configs.
Name
no_answer_timeout_secs
Type
integer | null
Description
How many seconds a transferred call rings before the no_answer_config takes over. null (or 0) means the no-answer flow is off and calls ring until they end naturally. Allowed values: 10, 20, 30, 40, 50, 60.
Name
opening_hours
Type
array
Description
Array of 7 objects (one per weekday) defining the opening schedule.

Call flow config types

All three routing slots — incoming_call_config, outside_opening_hours_config, and no_answer_config — share the same set of config types:

Type	Fields
`WelcomeTransferConfig`	`welcome` (string), `employee_ids` (non-empty array of strings)
`TransferConfig`	`employee_ids` (non-empty array of strings)
`RejectConfig`	`message` (string)
`VoicemailConfig`	`greeting` (string)
`PhoneMenuConfig`	`welcome` (string), `menu_options` (non-empty array)

TransferConfig transfers the call to the chosen employees without playing a welcome message — it's WelcomeTransferConfig minus the greeting.

employee_ids must contain at least one employee. An empty array is rejected with a 422 validation error.

Phone menu options

PhoneMenuConfig plays its welcome greeting, then waits for the caller to press a single digit. Each entry in menu_options maps one digit to an action:

Field	Type	Description
`digit`	string	A single key, `"1"` through `"9"` only (`"0"` is rejected). Must be unique within the menu.
`action_type`	string	What pressing the digit does (see below).
`prompt`	string	Message played before the action runs. Required when `action_type` is `WelcomeTransferConfig`, `VoicemailConfig`, or `PlayMessageConfig`.
`employee_ids`	array of strings	Transfer targets. Required (non-empty) for `TransferConfig` and `WelcomeTransferConfig`.

action_type is one of:

`action_type`	What happens when the caller presses the digit
`TransferConfig`	Transfer straight to `employee_ids`.
`WelcomeTransferConfig`	Play `prompt`, then transfer to `employee_ids`.
`VoicemailConfig`	Play `prompt`, then record a voicemail.
`PlayMessageConfig`	Play `prompt`, then hang up.

A menu needs at least one option, and every option's digit must be unique — duplicates or an empty menu_options array are rejected with a 422. On read, the response echoes each option's digit, action_type, prompt (when set), prompt_audio_url (generated audio), and employee_ids (resolved to public ids).

Send { "type": null } to clear the outside_opening_hours_config or no_answer_config slot entirely. The incoming_call_config slot can't be cleared.

GET/v1/main_numbers

List all main numbers

Returns every main number on the authenticated employee's company. There's no pagination — companies have a small, finite set of main numbers, so the response is a single array.

The list endpoint returns a lean response (id, name, number, number_formatted). Use the retrieve endpoint for full settings including routing config and opening hours.

Request

GET

/v1/main_numbers

curl https://app.phone.inc/api/v1/main_numbers \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "main_numbers": [
    {
      "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
      "name": "Sales",
      "number": "+14155551234",
      "number_formatted": "+1 415-555-1234"
    },
    {
      "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c02",
      "name": "Support",
      "number": "+14155555678",
      "number_formatted": "+1 415-555-5678"
    }
  ]
}

GET/v1/main_numbers/:id

Retrieve a main number

Returns the full settings for a single main number, including its incoming call config, outside-hours config, and weekly opening hours schedule.

Request

GET

/v1/main_numbers/:id

curl https://app.phone.inc/api/v1/main_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \
  -H "X-Api-Key: $PHONE_INC_API_KEY"

Response

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "name": "Sales",
  "number": "+14155551234",
  "number_formatted": "+1 415-555-1234",
  "timezone": "Copenhagen",
  "language": "da",
  "recording_enabled": false,
  "incoming_call_config": {
    "type": "PhoneMenuConfig",
    "welcome": "Press 1 for sales, 2 to leave a message",
    "welcome_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...",
    "menu_options": [
      {
        "id": 42,
        "digit": "1",
        "action_type": "TransferConfig",
        "prompt": null,
        "prompt_audio_url": null,
        "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"]
      },
      {
        "id": 43,
        "digit": "2",
        "action_type": "VoicemailConfig",
        "prompt": "Leave a message after the tone",
        "prompt_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...",
        "employee_ids": []
      }
    ]
  },
  "outside_opening_hours_config": {
    "type": "RejectConfig",
    "message": "We are closed, please call back tomorrow."
  },
  "no_answer_config": {
    "type": "VoicemailConfig",
    "greeting": "Sorry we missed you — leave a message after the tone."
  },
  "no_answer_timeout_secs": 30,
  "opening_hours": [
    { "day_of_week": 0, "day_name": "Monday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 1, "day_name": "Tuesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 2, "day_name": "Wednesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 3, "day_name": "Thursday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 4, "day_name": "Friday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 5, "day_name": "Saturday", "open": false, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 6, "day_name": "Sunday", "open": false, "opening_at": "09:00", "closing_at": "17:00" }
  ]
}

PATCH/v1/main_numbers/:id

Update a main number

Updates the scalar fields on a main number. Use the dedicated config endpoints below to change call routing or opening hours.

Accepted fields

Name
name
Type
string
Description
The display label for this number. ASCII letters, numbers, spaces, and -_~!.+ only, up to 128 characters.
Name
timezone
Type
string
Description
IANA timezone identifier, e.g. Copenhagen, London, New_York.
Name
language
Type
string
Description
Language code for automated messages: da, en, etc.
Name
recording_enabled
Type
boolean
Description
Whether to record calls on this number.

Request

PATCH

/v1/main_numbers/:id

curl -X PATCH https://app.phone.inc/api/v1/main_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01 \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales Hotline", "timezone": "London"}'

Response

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "name": "Sales Hotline",
  "number": "+14155551234",
  "number_formatted": "+1 415-555-1234",
  "timezone": "London",
  "language": "da",
  "recording_enabled": false,
  "incoming_call_config": { "..." },
  "outside_opening_hours_config": null,
  "no_answer_config": null,
  "no_answer_timeout_secs": null,
  "opening_hours": [ "..." ]
}

PUT/v1/main_numbers/:id/incoming_call_config

Replace incoming call config

Replaces the routing configuration used when a call comes in during opening hours. Send the desired type and its required fields. The full main number (with updated config) is returned.

Required fields by type

Type	Fields
`WelcomeTransferConfig`	`welcome`, `employee_ids` (at least one id)
`TransferConfig`	`employee_ids` (at least one id)
`RejectConfig`	`message`
`VoicemailConfig`	`greeting`
`PhoneMenuConfig`	`welcome`, `menu_options` (at least one option)

Request

PUT

/v1/main_numbers/:id/incoming_call_config

curl -X PUT https://app.phone.inc/api/v1/main_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "WelcomeTransferConfig",
    "welcome": "Thanks for calling",
    "employee_ids": ["019daef1-085e-7000-aaaa-000000000001", "019daef1-085e-7000-aaaa-000000000002"]
  }'

Response

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "name": "Sales",
  "number": "+14155551234",
  "number_formatted": "+1 415-555-1234",
  "timezone": "Copenhagen",
  "language": "da",
  "recording_enabled": false,
  "incoming_call_config": {
    "type": "WelcomeTransferConfig",
    "welcome": "Thanks for calling",
    "employee_ids": ["019daef1-085e-7000-aaaa-000000000001", "019daef1-085e-7000-aaaa-000000000002"]
  },
  "outside_opening_hours_config": null,
  "no_answer_config": null,
  "no_answer_timeout_secs": null,
  "opening_hours": [ "..." ]
}

To set a phone menu instead, send type: "PhoneMenuConfig" with a menu_options array:

Phone menu example

PUT

/v1/main_numbers/:id/incoming_call_config

curl -X PUT https://app.phone.inc/api/v1/main_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/incoming_call_config \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "PhoneMenuConfig",
    "welcome": "Press 1 for sales, 2 to leave a message",
    "menu_options": [
      { "digit": "1", "action_type": "TransferConfig", "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"] },
      { "digit": "2", "action_type": "VoicemailConfig", "prompt": "Leave a message after the tone" }
    ]
  }'

Response

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "name": "Sales",
  "number": "+14155551234",
  "number_formatted": "+1 415-555-1234",
  "timezone": "Copenhagen",
  "language": "da",
  "recording_enabled": false,
  "incoming_call_config": {
    "type": "PhoneMenuConfig",
    "welcome": "Press 1 for sales, 2 to leave a message",
    "welcome_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...",
    "menu_options": [
      {
        "id": 42,
        "digit": "1",
        "action_type": "TransferConfig",
        "prompt": null,
        "prompt_audio_url": null,
        "employee_ids": ["019daef1-085e-7000-aaaa-000000000001"]
      },
      {
        "id": 43,
        "digit": "2",
        "action_type": "VoicemailConfig",
        "prompt": "Leave a message after the tone",
        "prompt_audio_url": "https://app.phone.inc/rails/active_storage/blobs/redirect/...",
        "employee_ids": []
      }
    ]
  },
  "outside_opening_hours_config": null,
  "no_answer_config": null,
  "no_answer_timeout_secs": null,
  "opening_hours": [ "..." ]
}

PUT/v1/main_numbers/:id/outside_opening_hours_config

Replace outside-hours config

Replaces the routing configuration used when a call comes in outside opening hours. You can also update the opening hours schedule in the same request by including the opening_hours array.

Send { "type": null } to clear the outside-hours config entirely — calls will fall through to the regular incoming call config.

Required fields by type

Type	Fields
`RejectConfig`	`message`
`WelcomeTransferConfig`	`welcome`, `employee_ids` (at least one id)
`TransferConfig`	`employee_ids` (at least one id)
`VoicemailConfig`	`greeting`
`PhoneMenuConfig`	`welcome`, `menu_options` (at least one option)

Opening hours object

Name
day_of_week
Type
integer
Description
Day index: 0 = Monday, 6 = Sunday.
Name
open
Type
boolean
Description
Whether the line is open on this day.
Name
opening_at
Type
string
Description
Opening time in HH:MM format (24-hour).
Name
closing_at
Type
string
Description
Closing time in HH:MM format. Use 24:00 for end of day.

Request

PUT

/v1/main_numbers/:id/outside_opening_hours_config

curl -X PUT https://app.phone.inc/api/v1/main_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/outside_opening_hours_config \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "RejectConfig",
    "message": "We are closed, please call back tomorrow.",
    "opening_hours": [
      { "day_of_week": 0, "open": true, "opening_at": "09:00", "closing_at": "17:00" },
      { "day_of_week": 1, "open": true, "opening_at": "09:00", "closing_at": "17:00" },
      { "day_of_week": 2, "open": true, "opening_at": "09:00", "closing_at": "17:00" },
      { "day_of_week": 3, "open": true, "opening_at": "09:00", "closing_at": "17:00" },
      { "day_of_week": 4, "open": true, "opening_at": "09:00", "closing_at": "17:00" },
      { "day_of_week": 5, "open": false, "opening_at": "09:00", "closing_at": "17:00" },
      { "day_of_week": 6, "open": false, "opening_at": "09:00", "closing_at": "17:00" }
    ]
  }'

Response

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "name": "Sales",
  "number": "+14155551234",
  "number_formatted": "+1 415-555-1234",
  "timezone": "Copenhagen",
  "language": "da",
  "recording_enabled": false,
  "incoming_call_config": { "..." },
  "outside_opening_hours_config": {
    "type": "RejectConfig",
    "message": "We are closed, please call back tomorrow."
  },
  "no_answer_config": null,
  "no_answer_timeout_secs": null,
  "opening_hours": [
    { "day_of_week": 0, "day_name": "Monday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 1, "day_name": "Tuesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 2, "day_name": "Wednesday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 3, "day_name": "Thursday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 4, "day_name": "Friday", "open": true, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 5, "day_name": "Saturday", "open": false, "opening_at": "09:00", "closing_at": "17:00" },
    { "day_of_week": 6, "day_name": "Sunday", "open": false, "opening_at": "09:00", "closing_at": "17:00" }
  ]
}

PUT/v1/main_numbers/:id/no_answer_config

Replace no-answer config

Sets the flow that runs when a call is transferred to employees but nobody answers within the ring timer. Send the desired type, its required fields, and timeout_secs to arm the timer.

timeout_secs controls both the ring duration and whether the feature is on. Pass 10, 20, 30, 40, 50, or 60. Send "", 0, or null to turn it off — calls then ring until they end naturally, exactly as before. Any other value is rejected with a 422.

Send { "type": null } to clear the no-answer flow.

Don't put employees in this flow's WelcomeTransferConfig or TransferConfig and expect another timeout — the no-answer transfer rings without a timer, so it never loops back into itself.

Required fields by type

Type	Fields
`WelcomeTransferConfig`	`welcome`, `employee_ids` (at least one id)
`TransferConfig`	`employee_ids` (at least one id)
`RejectConfig`	`message`
`VoicemailConfig`	`greeting`
`PhoneMenuConfig`	`welcome`, `menu_options` (at least one option)

Accepted fields

Name
type
Type
string | null
Description
One of the call flow config types, or null to clear the slot.
Name
timeout_secs
Type
integer | null
Description
Ring timer in seconds: 10, 20, 30, 40, 50, or 60. 0, null, or a blank string ("", coerced to null server-side) turns the no-answer flow off.

Request

PUT

/v1/main_numbers/:id/no_answer_config

curl -X PUT https://app.phone.inc/api/v1/main_numbers/0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01/no_answer_config \
  -H "X-Api-Key: $PHONE_INC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "VoicemailConfig",
    "greeting": "Sorry we missed you — leave a message after the tone.",
    "timeout_secs": 30
  }'

Response

{
  "id": "0193f4a9-7c34-7c00-9e3d-2b2b8a7f1c01",
  "name": "Sales",
  "number": "+14155551234",
  "number_formatted": "+1 415-555-1234",
  "timezone": "Copenhagen",
  "language": "da",
  "recording_enabled": false,
  "incoming_call_config": { "..." },
  "outside_opening_hours_config": null,
  "no_answer_config": {
    "type": "VoicemailConfig",
    "greeting": "Sorry we missed you — leave a message after the tone."
  },
  "no_answer_timeout_secs": 30,
  "opening_hours": [ "..." ]
}