Bring Your Own Carrier
Availability: Not generally available yet. The provider requests follow each provider's published API, but no call has been placed through a customer account, so caller-ID acceptance is still unproven.
All paths below are relative to /api/v1/ext. Authentication and rate limits use the existing API-key middleware. Every operation requires carriers:manage and an organization-scoped key.
| Method | Path | Effect |
|---|---|---|
| GET | /carriers | List your connections |
| POST | /carriers | Encrypt credentials and save a pending connection |
| GET | /carriers/:id | Get the connection, imported numbers and configured SIP endpoint |
| DELETE | /carriers/:id | Stop outbound routing, mark its numbers inactive and soft-delete; retain all database rows |
| POST | /carriers/:id/verify | Check credentials; does not approve or attach numbers |
| GET | /carriers/:id/available-numbers | List account numbers available for individual import |
| POST | /carriers/:id/numbers | Import and re-route exactly one selected number |
| DELETE | /carriers/:id/numbers/:number | Detach an unbound number; retain its database row |
JWT-authenticated equivalents use /api/carriers. Only allmode operators can approve, suspend or resume through /api/allmode/carriers/:id/approve, /suspend and /resume, or list connections across organizations through /api/allmode/carriers. New connections always start pending_approval; verification alone cannot activate them. Unpaid self-serve trial organizations cannot create or approve a connection.
Connect
Use a label and exactly the credentials for your provider. Credentials are encrypted with the existing platform encryption key and are never returned. Keep them out of command histories and logs.
{
"provider": "twilio",
"label": "Our phone account",
"credentials": {
"account_sid": "<your account SID>",
"api_key_sid": "<your API key SID, starting with SK>",
"api_key_secret": "<that key's secret>"
}
}A Standard Twilio API key is recommended: you can revoke it without changing the Auth Token that controls your whole account. "auth_token": "<your auth token>" is still accepted in place of the two key fields, never together with them.
For Telnyx, use provider: "telnyx" and credentials: {"api_key": "<your API key>"}. Approval requires exactly one existing outbound voice profile in that account; otherwise select a single profile with your provider and retry approval. The platform does not guess an existing profile or create a billable one. Allow every country you will call on that profile: a new Telnyx profile allows only the US and Canada by default, and many destinations need Telnyx Level 2 verification first.
If an approval fails, the platform removes what it created in your account and the connection returns to pending approval, so it can be retried. Deleting a connection removes those resources as well, and marks its numbers inactive: their inbound calls are no longer answered, even if a SIP carrier still sends them. An imported number answers inbound calls only while its connection is active, so a suspended connection stops inbound as well as outbound. Its status follows import and detach and cannot be switched by hand.
For generic SIP:
{
"provider": "sip",
"label": "Our SIP carrier",
"credentials": {
"outbound_address": "sip.your-carrier.example:5060",
"transport": "udp",
"auth_username": "<your SIP username>",
"auth_password": "<your SIP password>"
},
"inbound_allowed_cidrs": ["<your carrier's actual signaling CIDR>"]
}Transport is udp, tcp or tls. Authentication fields must either both be supplied or both omitted. Generic SIP requires explicit non-global source CIDRs; custom CIDRs are rejected for Twilio/Telnyx. SIP verification validates configuration, not network reachability. Generic SIP has no account-number catalog: select and import a number manually after approval.
GET returns sip_endpoint only when the existing deployment setting is a configured non-vendor hostname. If it is missing, an operator must configure a controlled SIP hostname before giving the customer inbound configuration. Carrier creation does not configure DNS or deploy infrastructure.
Select, Import And Bind
Import changes how that number answers today. Confirm this for each number before importing it. No numbers are attached during approval or listing. Repeating a successful import of the same number is a no-op; a partially completed import is blocked for operator reconciliation, not blindly retried. A detached number, or one whose connection was deleted, can be imported again.
{"phone_number": "+12025550123"}POST that body to /carriers/:id/numbers, then bind the returned number ID through the existing POST /agents/:agent_id/phone-number with {"phone_number_id":"<imported-number-id>"} and phone_numbers:write. Binding updates the agent's caller ID. Check routing_live and any warning: an updated database binding alone is not inbound routing acceptance.
Carrier responses contain connection identity, your provider, label, status, sanitized status reason, concurrency cap and timestamps. They contain no credentials or internal trunk identifiers. GET additionally includes numbers with id, phone_number, status, and carrier_connection_id.
Unbind inbound and outbound agent assignments before detaching a number. Telnyx detachment remains manual until the account's detachment contract is confirmed: the API blocks the local number for operator reconciliation and sends no guessed detachment request. Detach does not restore its former provider connection, webhook or call flow. The number remains in the database as inactive on success, or blocked for reconciliation on an incomplete operation.
Calling And Safety
Published agents bound to an active imported number use that connection and caller ID for public, dashboard, campaign, callback and workflow calls. Ordinary agents without a carrier binding retain their existing routing. A pending, suspended, missing, deleted or errored bound carrier fails closed: it must not silently use a shared line or another of the organization's carriers. The normal country, do-not-call, trial and spend guards remain in force. The default per-connection cap is five live outbound call records; refused calls return CARRIER_CONCURRENCY_LIMIT. Calls through your connection are billed by your provider to your account. They carry no telephony charge from VoiceMatrix, only its platform charge. Suspension stops new carrier routing and removes its outbound trunk; it does not erase numbers or automatically restore inbound provider routing. Resuming rebuilds the outbound trunk with the same numbers and changes nothing in your carrier account.
Other actionable codes include TRIAL_CARRIER_NOT_ALLOWED, CARRIER_NOT_ACTIVE, NUMBER_NOT_OWNED, NUMBER_ALREADY_IMPORTED, NUMBER_BOUND, CARRIER_CALLER_ID_MISMATCH, CARRIER_PROVISIONING_FAILED, CARRIER_PROFILE_SELECTION_REQUIRED, and CARRIER_RECONCILIATION_REQUIRED. Public errors use {"error":{"code":"...","message":"..."}}. Mutations use the existing Idempotency-Key middleware; keep the same key when reconciling an uncertain HTTP response. A retained importing/detaching row or errored connection requires operator review.
MCP
The curated tools are list_carriers, list_carrier_numbers (carrier_id) and import_carrier_number (carrier_id, phone_number, confirm_reroute: true), all requiring carriers:manage. The import tool requires explicit rerouting confirmation and is annotated as modifying/open-world. No MCP tool accepts carrier credentials, approves a connection or buys a number.
Account Verification Still Required
The single Telnyx FQDN connection used for both directions needs an authorized customer check for caller-ID acceptance and outbound-profile permissions. Detachment-to-null remains manual until confirmed for the account; previous routing is never restored automatically. Published SIP signaling ranges are used, not webhook or media IP ranges. Unit tests use injected HTTP clients and fake telephony clients; no migration, provider request, deployment or real call runs as part of them.