trunks
List Transfer Directory
List the organization's transfer directory: the named people, queues and numbers its agents may transfer a call to, each with its target, hours, note, whether it is closed now and whether it reaches nothing (its trunk was deleted).
List Transfer Directory › Responses
Successful Response
closedcreated_atidkindWhat a directory entry reaches (rule 55): a phone number, normalised to E.164 like every number; or an extension, or an address the client's phone system gives a person, a queue or a group -- both held as text exactly as the system names them (rule 56) and reached only through the entry's trunk.
namereaches_nothingring_even_if_divertedtargetupdated_atCreate Transfer Directory Entry
Add a named destination to the transfer directory: a phone number, or an extension or address of your phone system with the trunk it is reached through. Owner or admin. A name already used, or a number that receives calls on the platform, is refused.
Create Transfer Directory Entry › Request Body
kindWhat a directory entry reaches (rule 55): a phone number, normalised to E.164 like every number; or an extension, or an address the client's phone system gives a person, a queue or a group -- both held as text exactly as the system names them (rule 56) and reached only through the entry's trunk.
nametargetring_even_if_divertedCreate Transfer Directory Entry › Responses
Successful Response
closedcreated_atidkindWhat a directory entry reaches (rule 55): a phone number, normalised to E.164 like every number; or an extension, or an address the client's phone system gives a person, a queue or a group -- both held as text exactly as the system names them (rule 56) and reached only through the entry's trunk.
namereaches_nothingring_even_if_divertedtargetupdated_atGet Transfer Directory Entry
Read one transfer directory entry.
path Parameters
entry_idGet Transfer Directory Entry › Responses
Successful Response
closedcreated_atidkindWhat a directory entry reaches (rule 55): a phone number, normalised to E.164 like every number; or an extension, or an address the client's phone system gives a person, a queue or a group -- both held as text exactly as the system names them (rule 56) and reached only through the entry's trunk.
namereaches_nothingring_even_if_divertedtargetupdated_atUpdate Transfer Directory Entry
Change a transfer directory entry: its name, target, trunk, hours, note or whether it rings even if the call was diverted from it. Owner or admin.
path Parameters
entry_idUpdate Transfer Directory Entry › Request Body
Update Transfer Directory Entry › Responses
Successful Response
closedcreated_atidkindWhat a directory entry reaches (rule 55): a phone number, normalised to E.164 like every number; or an extension, or an address the client's phone system gives a person, a queue or a group -- both held as text exactly as the system names them (rule 56) and reached only through the entry's trunk.
namereaches_nothingring_even_if_divertedtargetupdated_atList Trunks
List this organization's phone lines, optionally only inbound or
outbound: each one's number or extension, the agent it routes to, its trunk
(peer: the connection's settings, the peer recognised, what the peer must be
told of us), fallback number and whether the phone network can reach it
(reachability). Passwords are never included.
query Parameters
directionList Trunks › Responses
Successful Response
allowed_ipscarrier_failover_possibleThe per-kind guarantee, stated rather than left for the client to infer
from kind (rules 21-22): true only for a number the platform provides; a
line on a trunk of the client's own gets our routing's forward only.
created_atdirectionWhich way calls flow over the trunk.
fallback_conditionWhether the trunk is currently forwarding calls to its fallback number.
Binary on purpose: "A trunk can sit in fallback indefinitely... entering fallback raises a notification... and again when the condition clears" — the spec only ever names two states, not a severity scale.
idkindWhich peer a trunk connects to (trunks.md rule 4).
namenumberupdated_atanswer_bound_secondscarrierWhich carrier this line's calls cross: for a placing line, the carrier its trunk's SIP host is; for a receiving line, the host or else the addresses it accepts calls from; for a platform trunk, the deployment's own connection. telnyx, netelip, or unknown. Read-only; there is no setting for it.
fallback_answered_by_platformline_typeWhat a line's number is (trunks.md rule 7): a phone number, normalised to
E.164, or an extension of the client's phone system, held as text exactly as the
system names it and never read as a number.
reachabilityWhether the phone network can reach this line's trunk: incomplete (it lacks what its peer authenticates by), unreachable (the last run found no carrier-side object), reachable (a run within the last five minutes found it), or unknown (never reconciled, or not recently -- which is not health).
Deprecated: always null, kept for one release.
fallback_wait_secondsDeprecated: answer_bound_seconds, kept for one release.
reachableDeprecated: reachability == "reachable", kept for one release. False for an unknown trunk as well as an unreachable one; read reachability.
Create Trunk
Add a line -- a phone number or an extension -- on a new trunk, or on one of
this organization's trunks (peer_id). Use when a number has to exist on the
platform for the first time: an inbound line, pointed at the agent that answers
it, or an outbound one, which binds no agent — each call and campaign names its
own. A number is stored in E.164 and an extension as written; a number that
already receives calls on the platform is refused as taken, and so is an
extension on a trunk whose addresses another trunk shares. The answer shows
what the peer must be told of us (peer.our_side).
Create Trunk › Request Body
directionWhich way calls flow over the trunk.
namenumberallowed_ipsline_typeWhat a line's number is (trunks.md rule 7): a phone number, normalised to
E.164, or an extension of the client's phone system, held as text exactly as the
system names it and never read as a number.
Create Trunk › Responses
Successful Response
allowed_ipscarrier_failover_possibleThe per-kind guarantee, stated rather than left for the client to infer
from kind (rules 21-22): true only for a number the platform provides; a
line on a trunk of the client's own gets our routing's forward only.
created_atdirectionWhich way calls flow over the trunk.
fallback_conditionWhether the trunk is currently forwarding calls to its fallback number.
Binary on purpose: "A trunk can sit in fallback indefinitely... entering fallback raises a notification... and again when the condition clears" — the spec only ever names two states, not a severity scale.
idkindWhich peer a trunk connects to (trunks.md rule 4).
namenumberupdated_atanswer_bound_secondscarrierWhich carrier this line's calls cross: for a placing line, the carrier its trunk's SIP host is; for a receiving line, the host or else the addresses it accepts calls from; for a platform trunk, the deployment's own connection. telnyx, netelip, or unknown. Read-only; there is no setting for it.
fallback_answered_by_platformline_typeWhat a line's number is (trunks.md rule 7): a phone number, normalised to
E.164, or an extension of the client's phone system, held as text exactly as the
system names it and never read as a number.
reachabilityWhether the phone network can reach this line's trunk: incomplete (it lacks what its peer authenticates by), unreachable (the last run found no carrier-side object), reachable (a run within the last five minutes found it), or unknown (never reconciled, or not recently -- which is not health).
Deprecated: always null, kept for one release.
fallback_wait_secondsDeprecated: answer_bound_seconds, kept for one release.
reachableDeprecated: reachability == "reachable", kept for one release. False for an unknown trunk as well as an unreachable one; read reachability.
Get Trunk
Read one line: its number or extension and direction, the agent it routes to,
its trunk (peer), fallback number and conditions, and whether the phone
network can reach it (reachability). Passwords are never included.
path Parameters
trunk_idGet Trunk › Responses
Successful Response
allowed_ipscarrier_failover_possibleThe per-kind guarantee, stated rather than left for the client to infer
from kind (rules 21-22): true only for a number the platform provides; a
line on a trunk of the client's own gets our routing's forward only.
created_atdirectionWhich way calls flow over the trunk.
fallback_conditionWhether the trunk is currently forwarding calls to its fallback number.
Binary on purpose: "A trunk can sit in fallback indefinitely... entering fallback raises a notification... and again when the condition clears" — the spec only ever names two states, not a severity scale.
idkindWhich peer a trunk connects to (trunks.md rule 4).
namenumberupdated_atanswer_bound_secondscarrierWhich carrier this line's calls cross: for a placing line, the carrier its trunk's SIP host is; for a receiving line, the host or else the addresses it accepts calls from; for a platform trunk, the deployment's own connection. telnyx, netelip, or unknown. Read-only; there is no setting for it.
fallback_answered_by_platformline_typeWhat a line's number is (trunks.md rule 7): a phone number, normalised to
E.164, or an extension of the client's phone system, held as text exactly as the
system names it and never read as a number.
reachabilityWhether the phone network can reach this line's trunk: incomplete (it lacks what its peer authenticates by), unreachable (the last run found no carrier-side object), reachable (a run within the last five minutes found it), or unknown (never reconciled, or not recently -- which is not health).
Deprecated: always null, kept for one release.
fallback_wait_secondsDeprecated: answer_bound_seconds, kept for one release.
reachableDeprecated: reachability == "reachable", kept for one release. False for an unknown trunk as well as an unreachable one; read reachability.
Update Trunk
Change a line's number, name, or which agent answers it, and its trunk's settings, which every line on that trunk shares. Use when re-pointing an existing inbound number at a different agent, renaming it, or setting or clearing its fallback; an agent and a fallback number belong to an inbound line only, and one of the platform's own agents is refused.
path Parameters
trunk_idUpdate Trunk › Request Body
Update Trunk › Responses
Successful Response
allowed_ipscarrier_failover_possibleThe per-kind guarantee, stated rather than left for the client to infer
from kind (rules 21-22): true only for a number the platform provides; a
line on a trunk of the client's own gets our routing's forward only.
created_atdirectionWhich way calls flow over the trunk.
fallback_conditionWhether the trunk is currently forwarding calls to its fallback number.
Binary on purpose: "A trunk can sit in fallback indefinitely... entering fallback raises a notification... and again when the condition clears" — the spec only ever names two states, not a severity scale.
idkindWhich peer a trunk connects to (trunks.md rule 4).
namenumberupdated_atanswer_bound_secondscarrierWhich carrier this line's calls cross: for a placing line, the carrier its trunk's SIP host is; for a receiving line, the host or else the addresses it accepts calls from; for a platform trunk, the deployment's own connection. telnyx, netelip, or unknown. Read-only; there is no setting for it.
fallback_answered_by_platformline_typeWhat a line's number is (trunks.md rule 7): a phone number, normalised to
E.164, or an extension of the client's phone system, held as text exactly as the
system names it and never read as a number.
reachabilityWhether the phone network can reach this line's trunk: incomplete (it lacks what its peer authenticates by), unreachable (the last run found no carrier-side object), reachable (a run within the last five minutes found it), or unknown (never reconciled, or not recently -- which is not health).
Deprecated: always null, kept for one release.
fallback_wait_secondsDeprecated: answer_bound_seconds, kept for one release.
reachableDeprecated: reachability == "reachable", kept for one release. False for an unknown trunk as well as an unreachable one; read reachability.
List Forward Records
List the calls this line forwarded on, newest first. Use when checking a line's forwarding history.
path Parameters
trunk_idList Forward Records › Responses
Successful Response
created_atidoriginWhich of the two places forwarded a given call — "Two guarantees, and they are not the same size" (docs/features/trunks.md). Kept apart because they carry different evidentiary weight: one is first-hand, the other is hearsay we may never receive.
reasontrunk_idoutcomeWhat became of a call the trunk could not put through to its agent. A
trunk with a fallback number FORWARDED it there; one with none left it
UNSERVED -- it reached nobody (trunks.md rule 34, #361). Its own column and
not an inference from forwarded_to IS NULL, which a carrier-edge record
may also carry.