Create a sandbox number (test mode)

POST

/phone_numbers

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const phoneNumber = await mv.phoneNumbers.create({
  assistant_id: "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
  label: "Support line (test)",
});
console.log(phoneNumber);

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

phone_number = client.phone_numbers.create({
    "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
    "label": "Support line (test)",
})
print(phone_number)

curl -X POST https://api.morevoice.ai/v1/phone_numbers \
  -H "Authorization: Bearer $MOREVOICE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "label": "Support line (test)"
}'

With a test key: allocates a sandbox number (source: sandbox) in the +972 50 999 range, at no cost and with no carrier, at most 5 per organisation. Dial it with POST /v1/test_helpers/inbound_calls. A sandbox number never receives real calls. With a live key the endpoint is not available yet (buy numbers in the dashboard).

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

application/json

Test mode only: allocates a sandbox number (no carrier, no cost; at most 5 per organisation). Set at most one of assistant_id, flow_id and inbound_route_id; with none, test calls reach your most recently updated assistant, as on a real line.

object

assistant_id

Inbound test calls to the number reach this assistant.

string

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

flow_id

Inbound test calls to the number run this published flow.

string

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

inbound_route_id

Inbound test calls to the number follow this inbound route.

string

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

label

A name for the number, shown in lists.

string

<= 100 characters

Example

{
  "assistant_id": "asst_4Gk2LmN9pQ4rS6tV8wX0yZ",
  "label": "Support line (test)"
}

Responses

201

Created

application/json

A phone number on your account.

object

connection_id

required

Any of:

string
null

The connection that carries the number, or null.

string

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

country

required

ISO 3166-1 alpha-2, when known.

string | null

created

required

Any of:

string
null

An ISO-8601 timestamp in UTC.

string format: date-time

e164

required

The number in E.164.

string

required

The number’s ID (stable).

string

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

inbound

required

Calls to the number are answered here (a route or connection matches it).

boolean

inbound_route_id

required

Any of:

string
null

The route that matches calls to the number (exactly), or null.

string

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

label

required

string | null

livemode

required

true in live mode, false in test mode.

boolean

object

required

string

Allowed value: phone_number

outbound_caller_id

required

The number can be presented as caller ID on outbound calls.

boolean

provider

required

The carrier of a provisioned number; null for your own connections.

string | null

source

required

provisioned: bought through the platform. connection: a number of your own SIP connection (its caller IDs and the numbers your inbound routes match). sandbox: a test-mode number.

string

Allowed values: provisioned connection sandbox

status

required

active; provisioned numbers can also be pending, pending_kyc, porting_in, suspended, releasing or released.

string

Example

{
  "connection_id": "conn_2Wq8RfLx0bZt7nKp1VdYhC",
  "country": "IL",
  "created": null,
  "e164": "+97231234567",
  "id": "pn_3TzKk4u7Q0Yx9b2LmN8pQr",
  "inbound": true,
  "inbound_route_id": "rte_5Hn3MpO0qR5sT7uW9xY1zA",
  "label": "Main trunk",
  "livemode": true,
  "object": "phone_number",
  "outbound_caller_id": true,
  "provider": null,
  "source": "connection",
  "status": "active"
}

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.