Skip to content
MoreVoiceDevelopers

Retrieve a connection

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


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


const connection = await mv.connections.retrieve("conn_rtcFZ4v7Gg3mfomNppGQci");
console.log(connection);

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

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string
<= 200 characters /^conn_[0-9A-Za-z]+$/

A connection ID (conn_…).

Header Parameters

Section titled “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

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json

A SIP trunk or registration to your carrier. Live mode only.

object
active_calls
required

Calls on the connection right now.

integer
>= -9007199254740991 <= 9007199254740991
answer_inbound
required

Answer inbound calls on this connection.

boolean
auth_username
required

The authentication user, when it differs from username.

string
backend
required

native: the platform’s own SIP stack. freeswitch: FreeSWITCH in front.

string
Allowed values: native freeswitch
caller_ids
required

Numbers this connection may present as caller ID.

Array<string>
codecs
required

Audio codecs, in preference order.

Array<string>
Allowed values: pcma pcmu
created
required

An ISO-8601 timestamp in UTC.

string format: date-time
default_caller_id
required

The caller ID used when a call names none.

string
display_name
required
string
enabled
required

Disabled connections neither register nor carry calls.

boolean
host
required

The carrier’s SIP host.

string
id
required

The connection’s ID.

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

Trunks: extra source IPs / CIDRs allowed to send calls (the host’s addresses always are).

Array<string>
inbound_assistant_id
required
Any of:

The assistant that answers inbound calls no inbound route matches, or null.

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

Share of max_channels outbound campaigns never use, kept for inbound calls.

integer
>= -9007199254740991 <= 9007199254740991
livemode
required

true in live mode, false in test mode.

boolean
max_channels
required

Simultaneous calls (0: unlimited).

integer
>= -9007199254740991 <= 9007199254740991
max_cps
required

New outbound calls per second (0: unlimited).

integer
>= -9007199254740991 <= 9007199254740991
name
required
string
object
required
string
Allowed value: connection
overflow_policy
required

When the connection is full: busy (486) or unavailable (503, lets a carrier fail over).

string
Allowed values: busy unavailable
password_set
required

Whether a password is stored. Passwords are write-only.

boolean
port
required
integer
>= -9007199254740991 <= 9007199254740991
register
required

Send REGISTER to the host.

boolean
register_expires_seconds
required
integer
>= -9007199254740991 <= 9007199254740991
status
required

The connection’s live state.

object
error
required

The last registration error, or null.

string | null
expires_seconds
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
registered_at
required
Any of:

An ISO-8601 timestamp in UTC.

string format: date-time
state
required

registered / listening: ready. incomplete: settings are missing. failed: see error.

string
Allowed values: disabled incomplete registering registered listening failed
transport
required
string
Allowed values: udp
type
required

registration: registers like a phone/extension. trunk: a carrier trunk (IP or credential authentication).

string
Allowed values: registration trunk
updated
required

An ISO-8601 timestamp in UTC.

string format: date-time
username
required
string
Example
{
  "active_calls": 2,
  "answer_inbound": true,
  "auth_username": "",
  "backend": "native",
  "caller_ids": [
    "+97231234567"
  ],
  "codecs": [
    "pcma",
    "pcmu"
  ],
  "created": "2026-11-03T09:14:22.000Z",
  "default_caller_id": "+97231234567",
  "display_name": "",
  "enabled": true,
  "host": "sip.carrier.example.com",
  "id": "conn_2Wq8RfLx0bZt7nKp1VdYhC",
  "inbound_acl": [
    "198.51.100.0/24"
  ],
  "inbound_assistant_id": "asst_3cYbE6uYvGkH8w4ZK1rTqd",
  "inbound_reserve_pct": 15,
  "livemode": true,
  "max_channels": 30,
  "max_cps": 5,
  "name": "Main trunk",
  "object": "connection",
  "overflow_policy": "busy",
  "password_set": false,
  "port": 5060,
  "register": false,
  "register_expires_seconds": 300,
  "status": {
    "error": null,
    "expires_seconds": null,
    "registered_at": null,
    "state": "listening"
  },
  "transport": "udp",
  "type": "trunk",
  "updated": "2026-11-03T09:14:22.000Z",
  "username": ""
}

400

Section titled “400”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

401

Section titled “401”

No valid API key was sent.

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

403

Section titled “403”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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

404

Section titled “404”

No object with this ID exists in this organisation and mode.

Media typeapplication/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": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

Section titled “Headers”
X-Request-Id
string

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

429

Section titled “429”

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

Media typeapplication/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

Section titled “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

Section titled “500”

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

Media typeapplication/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

Section titled “Headers”
X-Request-Id
string

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