Create an inbound route

POST

/inbound_routes

import { createClient, createResources } from "@morevoice/sdk";

const mv = createResources({
  client: createClient({ baseUrl: "https://api.morevoice.ai/v1", auth: process.env.MOREVOICE_API_KEY }),
});

const inboundRoute = await mv.inboundRoutes.create({
  fallback_assistant_id: "asst_3cYbE6uYvGkH8w4ZK1rTqd",
  match_did: "+97231234567",
  name: "Sales line",
  target: {
    queue_id: "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
    type: "queue",
  },
});
console.log(inboundRoute);

import os
import uuid

import requests

response = requests.post(
    "https://api.morevoice.ai/v1/inbound_routes",
    headers={"Authorization": f"Bearer {os.environ['MOREVOICE_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "fallback_assistant_id": "asst_3cYbE6uYvGkH8w4ZK1rTqd",
        "match_did": "+97231234567",
        "name": "Sales line",
        "target": {
            "queue_id": "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
            "type": "queue",
        },
    },
)
response.raise_for_status()
print(response.json())

curl -X POST https://api.morevoice.ai/v1/inbound_routes \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "fallback_assistant_id": "asst_3cYbE6uYvGkH8w4ZK1rTqd",
  "match_did": "+97231234567",
  "name": "Sales line",
  "target": {
    "queue_id": "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
    "type": "queue"
  }
}'

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Idempotency-Key

string

>= 1 characters <= 255 characters

A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.

Example

5f0c1e8a-7b2d-4c3e-9f1a-2b6d8e4c0a17

Request Body^required

application/json

A new route. target is required; other fields default (enabled, priority 100, match anything).

object

connection_id

Any of:

string
null

Only calls on this connection; null for any.

string

<= 200 characters /^conn_[0-9A-Za-z]+$/

enabled

boolean

fallback_assistant_id

Any of:

string
null

Answers when the target cannot take the call; null for none. Not with an assistant target.

string

<= 200 characters /^asst_[0-9A-Za-z]+$/

match_caller

The caller’s number: exact, a prefix ending in *, or empty for any.

string

<= 40 characters /^\+?[0-9\s()-]*\*?$/

match_did

The dialled number: exact, a prefix ending in *, or empty for any.

string

<= 40 characters /^\+?[0-9\s()-]*\*?$/

name

string

<= 120 characters

priority

integer

>= -100000 <= 100000

target

required

Where a matching call goes: type, and the ID in <type>_id.

object

assistant_id

With type: assistant.

string

<= 200 characters /^asst_[0-9A-Za-z]+$/

conference_room_id

With type: conference_room.

string

<= 200 characters /^room_[0-9A-Za-z]+$/

flow_id

With type: flow (a published voice flow).

string

<= 200 characters /^flow_[0-9A-Za-z]+$/

queue_id

With type: queue.

string

<= 200 characters /^q_[0-9A-Za-z]+$/

type

required

What answers: assistant — an AI assistant answers; flow — a published voice flow (IVR) runs; queue — the call waits in a queue for a human agent; user — one person’s direct line (their forwarding rules apply); conference_room — a conference room (PIN prompt, then join). The ID goes in the field <type>_id.

string

Allowed values: assistant flow queue user conference_room

user_id

With type: user.

string

<= 200 characters /^usr_[0-9A-Za-z]+$/

Responses

201

The new route.

application/json

A rule that sends inbound calls (by dialled number and caller) to an assistant, flow, queue, person or room.

object

connection_id

required

Any of:

string
null

Only calls arriving on this connection, or null for any.

string

/^conn_[0-9A-Za-z]+$/

created

required

An ISO-8601 timestamp in UTC.

string format: date-time

enabled

required

boolean

fallback_assistant_id

required

Any of:

string
null

Answers when the target cannot take the call (a disabled queue, a deactivated user), or null.

string

/^asst_[0-9A-Za-z]+$/

required

The route’s ID.

string

/^rte_[0-9A-Za-z]+$/

livemode

required

true in live mode, false in test mode.

boolean

match_caller

required

The caller’s number: exact, a prefix ending in *, or empty for any.

string

match_did

required

The dialled number: exact, a prefix ending in *, or empty for any.

string

name

required

string

object

required

string

Allowed value: inbound_route

priority

required

Lower runs first; the first matching route wins.

integer

>= -9007199254740991 <= 9007199254740991

target

required

Any of:

object
null

Where a matching call goes.

object

assistant_id

With type: assistant.

string

/^asst_[0-9A-Za-z]+$/

conference_room_id

With type: conference_room.

string

/^room_[0-9A-Za-z]+$/

flow_id

With type: flow.

string

/^flow_[0-9A-Za-z]+$/

queue_id

With type: queue.

string

/^q_[0-9A-Za-z]+$/

type

required

string

Allowed values: assistant flow queue user conference_room

user_id

With type: user.

string

/^usr_[0-9A-Za-z]+$/

Example

{
  "connection_id": "conn_2Wq8RfLx0bZt7nKp1VdYhC",
  "created": "2026-11-03T09:14:22.000Z",
  "enabled": true,
  "fallback_assistant_id": "asst_3cYbE6uYvGkH8w4ZK1rTqd",
  "id": "rte_5Hn3MpO0qR5sT7uW9xY1zA",
  "livemode": true,
  "match_caller": "",
  "match_did": "+97231234567",
  "name": "Sales line",
  "object": "inbound_route",
  "priority": 100,
  "target": {
    "queue_id": "q_4Gk2LmN9pQ4rS6tV8wX0yZ",
    "type": "queue"
  }
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

409

The request conflicts with the object’s state, or the Idempotency-Key was reused with other parameters.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "idempotency_mismatch",
    "doc_url": "https://docs.morevoice.ai/api/errors#idempotency-mismatch",
    "message": "This Idempotency-Key was already used with different parameters.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "idempotency_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

Create an inbound route

Authorizations

Parameters

Header Parameters

Example

Example

Request Bodyrequired

Responses

201

Example

400

Example

Headers

401

Example

Headers

403

Example

Headers

409

Example

Headers

429

Example

Headers

500

Example

Headers

Request Body^required