Signals Docs
SIP Trunks

Bring your own carrier

Bring your own carrier (BYOC) lets you send and receive calls through a carrier you already have a contract with, instead of PressOne's own routes to the phone network. You keep your carrier, its rates and its numbers. Signals carries the calls between that carrier and your trunks or voice applications, applies the limits you set, and records every call.

You connect a carrier with a carrier connection. Its ID starts with byo_, for example byo_01a19b7e-deee-779d-953d-a3f8be2d1617. In the console, carrier connections are under Carriers.

How a connection works

A connection brings together these parts:

PartWhat it controlsField or endpoint
DirectionWhether the connection carries calls from your carrier, to it, or both.direction: inbound, outbound or both
HostnameThe address your carrier sends calls to. Signals derives it from the name.signaling_fqdn
AuthenticationHow Signals recognises calls that come from your carrier.ingress_sources, generate_password, then /byoc/connections/{connection_id}/ingress-credentials
Inbound destinationThe trunk that rings when a call arrives for one of the connection's numbers.inbound_trunk_id
PeersWhere Signals sends outbound calls: the SIP addresses of your carrier.peers on create, then /byoc/connections/{connection_id}/peers
NumbersThe numbers your carrier holds for you, which this connection carries.POST /numbers/hosted
LimitsHow many calls run at once, how fast new calls start, and how long a call may last.ceilings
MediaWhich audio codecs the connection offers and whether audio is encrypted.g729, media_security

A connection that takes inbound calls (inbound or both) needs an inbound destination and at least one authentication method. A connection that sends outbound calls (outbound or both) needs at least one peer. The API refuses an enabled connection that is missing either.

Create a connection

In the console, open Carriers and choose Connect a carrier. The steps are Basics, Peers, Authentication, Inbound destination, Numbers and Review. With the API, send everything in one request:

TerminalCode
curl -X POST "$SIGNALS/byoc/connections" \ -H "Signals-Version: 2026-10-27" \ -H "Authorization: Bearer $SIGNALS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9b2f4c71-3e8a-4d06-b5c1-7a0e2f6d8c43" \ -d '{ "name": "airtel-direct", "direction": "both", "inbound_trunk_id": "trk_01992f3a-6c1e-7d42-9b8a-5e7f0c2d1a94", "peers": [ { "host": "sbc1.carrier.example", "port": 5060, "transport": "udp", "priority": 1, "weight": 100 }, { "host": "sbc2.carrier.example", "port": 5060, "transport": "udp", "priority": 2, "weight": 100 } ], "ingress_sources": [{ "cidr": "203.0.113.0/28" }], "generate_password": false, "media_security": "rtp", "g729": false, "number_format": "e164_plus", "identity_policy": "from_only", "privacy_passthrough": false, "tech_prefix": null, "strip": 0, "ceilings": { "max_concurrent": 30, "max_cps": 5, "max_call_duration_seconds": 7200 }, "failover_sip_codes": [408, 480, 500, 503], "peer_timeout_seconds": 8, "attempt_deadline_seconds": 30 }'

The API answers 201 Created with the connection under connection, and password set when you asked for one with "generate_password": true. The password is shown once. Store it before you leave the page or discard the response.

  • The name is lowercase letters, digits and hyphens, and starts and ends with a letter or digit. Trunks and connections share one set of names, so a name a trunk already uses is refused with 409 carrier_connection_name_conflict.
  • inbound_trunk_id must name a trunk of the same project that takes inbound calls. Omitting it on an inbound connection returns 422 inbound_trunk_required; sending it on an outbound connection returns 422 inbound_trunk_not_allowed. A trunk that cannot take calls returns 409 carrier_connection_target_conflict with a reason, as in Numbers and routing.
  • Edits use PATCH /byoc/connections/{connection_id} with the connection's ETag in If-Match, as for trunks. See Revisions and ETags.

What to give your carrier

Your carrier needs four things from you. The console shows them together on the connection's page and on the completion page after you create it.

ItemValue
Where to send callsThe connection's hostname, for example airtel-direct.sip.trunk.pressone.co.
PortsSIP over UDP and TCP on 5060, and SIP over TLS on 5061.
Signals addressessignaling_nodes and media_cidrs from platform endpoints, for your carrier's firewall.
CredentialsThe username and password, if the connection uses a password. The realm is the hostname.

Your carrier must send calls to the connection's hostname, not to sip.trunk.pressone.co or an IP address. Signals identifies the connection by the hostname a call is addressed to. A call to the bare domain is treated as a trunk call and is not matched to your connection.

Authentication

Signals must know that a call really comes from your carrier before it carries it. A connection uses an IP list, a password, or both:

  • IP list: Signals accepts calls only from the networks in ingress_sources. A call from any other address is refused with 403 and no challenge.
  • Password: your carrier answers a digest challenge with the connection's username and password. The realm is the connection's hostname.
  • Both: a call must come from a listed network and answer the challenge.

POST /byoc/connections/{connection_id}/ingress-credentials generates a password when the connection has none. To change it, rotate it with POST /byoc/connections/{connection_id}/ingress-credentials/{credential_id}/rotate. The response shows the new password once, and replaced_valid_until tells you how long the old password keeps working, so your carrier can switch over without dropped calls.

If you rename a connection, its hostname changes with it. Passwords keep the realm they were generated with until you rotate them; the next password uses the new hostname.

Numbers your carrier holds

Numbers your carrier gives you are hosted numbers. You import them onto the connection so Signals knows which connection a call to each number belongs to:

TerminalCode
curl -X POST "$SIGNALS/numbers/hosted" \ -H "Signals-Version: 2026-10-27" \ -H "Authorization: Bearer $SIGNALS_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 1e7c3a52-9f4b-4d81-a6e0-2b8d5f1c9a74" \ -d '{ "connection_id": "byo_01a19b7e-deee-779d-953d-a3f8be2d1617", "numbers": ["+2347009990100", "+2347009990101", "+2347009990102"] }'

One request takes 1 to 5,000 distinct Nigerian numbers in E.164 form. Signals groups consecutive numbers into blocks of at most 1,000 and answers with the blocks it created. Hosted numbers carry no setup or monthly fee from Signals; your carrier bills you for them.

A call your carrier sends for a number that is not imported on that connection is refused with 404 NUMBER_NOT_REGISTERED, even if the number is imported on another of your connections.

Where hosted numbers ring

A number's route decides where a call goes. The connection fills in the route for its numbers:

  • A hosted number with no route rings the connection's inbound destination trunk.
  • You can route a hosted block, or a slice of it, to any trunk or voice application, exactly as you route a Signals block. See Route numbers to a trunk.
  • A null target on a hosted slice returns those numbers to the connection's trunk.

If a route points at a trunk that cannot take calls, for example one that is suspended, the call is refused with 480 DESTINATION_UNAVAILABLE. It does not fall back to the connection's trunk.

A hosted number is also a caller ID: a trunk may present the hosted numbers that ring it, and a voice application may use a hosted number as its From.

Outbound calls

The caller ID decides how an outbound call leaves. A call whose caller ID is one of the connection's hosted numbers goes out through that connection; a call whose caller ID is a Signals number goes out through PressOne. You do not choose per call.

Signals tries your peers with the lowest priority value first. Peers that share a priority split calls by weight. A peer has peer_timeout_seconds to answer. If it does not, or it answers with one of the failover_sip_codes, Signals tries the next peer. attempt_deadline_seconds limits the whole attempt and must be longer than the peer timeout.

Signals never sends a connection's call through PressOne's routes. If every peer fails, the call fails. If the connection is disabled or does not send outbound calls, a call with its caller ID is refused with 503 EGRESS_UNAVAILABLE.

These settings shape the call your carrier receives:

FieldWhat it does
number_formatHow the dialled number is written: e164_plus (+2348031234567), e164 (2348031234567) or national (08031234567).
tech_prefixOne to fifteen digits put before the dialled number, if your carrier asks for one.
stripLeading digits removed from the dialled number, up to 14.
identity_policyfrom_only sends the caller ID in From; from_and_pai also sends it in P-Asserted-Identity.
privacy_passthroughtrue passes the caller's privacy request on to your carrier.
media_securityrtp or sdes_srtp_required. Encrypted media needs every peer on tls.

From a voice application

Calls from a voice application follow the same rule: the From number decides. The Calls API also accepts Byoc with the connection ID, as Twilio does. It must name the connection of the From number, or the call is refused. <Dial byoc> and <Number byoc> work the same way in OneML.

Refused calls

Calls your carrier sends can be refused before they ring anything. The reply tells your carrier why:

ReplyMeaning
404 UNKNOWN_HOSTThe call is addressed to a name under sip.trunk.pressone.co that is not a connection or a trunk. Check the hostname for a typo.
403 SOURCE_NOT_PERMITTEDThe call came from an address that is not on the IP list, or the connection is disabled or does not take inbound calls.
407The connection uses a password, and the carrier has not answered the challenge yet.
403 AUTHENTICATION_FAILEDThe username or password is wrong.
404 NUMBER_NOT_REGISTEREDThe dialled number is not imported on this connection.
480 DESTINATION_UNAVAILABLEThe number's route, or the connection's trunk, cannot take calls.

Refusals after authentication appear in your call history as rejected calls on the connection's trunk, with their SIP code and the connection. They are never charged. Refusals before authentication, 403 from the IP list and wrong passwords, are not calls: the connection's refusals field counts them and shows the last time, source address and reason. The count is approximate, because Signals writes it at most once a minute per connection.

Pricing

A call through a connection is charged a flat platform fee per minute instead of PressOne's destination rates, under call.byoc.inbound and call.byoc.outbound. Your carrier bills you for the call itself. There is no fee for the connection or its numbers. Your rates are in the console under Billing. Spend caps and daily budgets in your outbound policy count BYOC calls at this fee.

Disable or release a connection

POST /byoc/connections/{connection_id}/disable stops new calls through the connection; calls in progress continue. POST /byoc/connections/{connection_id}/enable allows them again.

DELETE /byoc/connections/{connection_id} releases a connection. You confirm the exact connection name in the body. The API refuses with 409 carrier_connection_referenced while the connection still has hosted numbers. Remove them first with DELETE /numbers/hosted/{block_id}. A trunk that is a connection's inbound destination cannot be released until you choose another destination for the connection.

Last modified on