Number configuration

Everything you can set on a number’s Answer page in the dashboard can also be read and changed over the API. A change made here is saved through the same code path as the dashboard’s Save button, so it applies from the next call or text on every number, whichever stack it runs on.

Endpoint	What it does	Scope
`GET /v1/phone-numbers/{id}/config`	The number’s full configuration	`phone_numbers:read`
`PATCH /v1/phone-numbers/{id}/config`	Change any part of it; returns the full updated config	`phone_numbers:write`
`GET /v1/phone-numbers/{id}/voices`	Voices the number’s agent can speak with	`phone_numbers:read`

{id} is the numeric id from GET /v1/phone-numbers. Reads and changes are free. AI agents can do the same through the MCP server with get_phone_number_config, update_phone_number_config and list_phone_number_voices.

Sections

The configuration is grouped the way the dashboard’s tabs are:

Section	Dashboard tab	Holds
`name`, `is_active`, `business_name`, `business_description`, `timezone`	Setup	Basics. `is_active: false` stops the number answering calls.
`call_settings`	Setup	Max call length, recording, transcription, summaries, recording retention, HD Voice (T2 numbers only)
`voice`	Voice & Personality	Voice, language, speed, greeting, farewell, your call prompt, LLM, background sound, outbound greeting/prompt
`sms`	Voice & Personality, top bar	SMS auto-reply on/off, reply delay, SMS prompt, language, LLM, stop words, max replies per contact
`knowledge`	Knowledge, Setup	Knowledge documents and FAQs the agent can use, knowledge and web-search toggles
`qualification`	Qualification	Qualification on/off, which contact details to collect, qualifying questions
`booking`	Booking	Booking on/off, bookable event types, bookable hours and days, minimum notice, confirmation message
`transfers`	Routing: In-Call Transferring	Transfer number, transfer rules, office-hours window for live transfers
`sms_referrals`	Routing: SMS Transferring	Which number to refer texters to, and when
`forwarding`	Routing: Call Forwarding	AI answers everything, or “call me first” with a single number or a ring chain
`ivr`	Phone Menu (IVR)	The “press 1, press 2” keypad menu that answers instead of the AI when enabled

voice and sms report inherits_workspace_default: true while the number still uses your workspace’s default settings. The first change you make to either one gives the number its own copy, starting from those defaults, so nothing you didn’t mention changes.

How updates work

Send only what you want to change. Inside a section, fields you leave out keep their current value.
Lists are replaced as a whole: transfers.rules, qualification.questions, sms_referrals, forwarding.sequential_targets and ivr.menus. Fetch the config, edit the list, and send the whole list back. Items keep their id; leave id out to add a new one. A qualifying question you leave out is removed.
Unknown fields are rejected with a 400, so a typo never silently does nothing.
The response is the full configuration after the change.

Examples

Change the voice and the prompt

Pick a voice from the number’s voice list:

curl "https://api.lumisreach.com/api/v1/phone-numbers/42/voices" \
  -H "Authorization: Bearer YOUR_API_KEY"

Then set it along with the agent’s instructions and greeting:

curl -X PATCH "https://api.lumisreach.com/api/v1/phone-numbers/42/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice": {
      "voice_id": "Kore",
      "greeting_message": "Thanks for calling Bayside Dental, this is Ava. How can I help?",
      "prompt": "You are the front desk for Bayside Dental. Keep answers short. Never quote prices."
    }
  }'

Set the transfer number

curl -X PATCH "https://api.lumisreach.com/api/v1/phone-numbers/42/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transfers": {
      "primary_transfer_number": "+14155550123",
      "office_hours_only": true,
      "office_hours_start": "09:00",
      "office_hours_end": "17:00"
    }
  }'

Cap SMS auto-replies at 30 per contact

The default is 50.

curl -X PATCH "https://api.lumisreach.com/api/v1/phone-numbers/42/config" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sms": { "stop_after_replies": true, "max_replies_per_contact": 30 } }'

Replace the transfer rules

{
  "transfers": {
    "rules": [
      {
        "condition": "human_requested",
        "action": "transfer",
        "target_number": "+14155550123",
        "priority": 0
      },
      { "condition": "after_hours", "action": "voicemail", "priority": 1 },
      {
        "condition": "custom",
        "custom_condition": "The caller reports a dental emergency",
        "action": "transfer",
        "target_number": "+14155550199",
        "priority": 2
      }
    ]
  }
}

{
  "ivr": {
    "enabled": true,
    "greeting": "Thanks for calling Bayside Dental.",
    "menus": [
      {
        "id": "main",
        "name": "Main menu",
        "options": [
          {
            "key": "1",
            "label": "Appointments",
            "action": { "type": "transfer", "phone_number": "+14155550123" }
          },
          {
            "key": "2",
            "label": "Billing",
            "action": {
              "type": "transfer",
              "phone_number": "+14155550124",
              "fallback_phone_number": "+14155550123"
            }
          }
        ]
      }
    ],
    "timeout_seconds": 5,
    "max_attempts": 3,
    "fallback": { "type": "hangup" }
  }
}

The first time you enable a menu, send the whole menu as above. After that you can change single fields, such as { "ivr": { "enabled": false } }.

Stack differences

Every setting works on both stacks, with three exceptions that follow the dashboard:

Setting	Applies to
`call_settings.hd_voice_enabled`	T2 (Telnyx + LiveKit) numbers only; T1 numbers return `400`
`voice.voice_model_tier`	T2 numbers only
`voice.speed`	T1 (Twilio + VAPI) numbers only

GET /config reports the number’s stack as t1 or t2.

Not covered here

Creating or editing the knowledge documents and FAQs themselves (you can assign existing ones with knowledge.knowledge_base_ids and knowledge.faq_ids), creating event types, and generating or running the Tests tab’s test calls stay in the dashboard for now.

Getting Started

Concepts

Quick Agent Actions

Conversation History

Phone Numbers