# 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:

| Part | What it controls | Field or endpoint |
| --- | --- | --- |
| Direction | Whether the connection carries calls from your carrier, to it, or both. | `direction`: `inbound`, `outbound` or `both` |
| Hostname | The address your carrier sends calls to. Signals derives it from the name. | `signaling_fqdn` |
| Authentication | How Signals recognises calls that come from your carrier. | `ingress_sources`, `generate_password`, then `/byoc/connections/{connection_id}/ingress-credentials` |
| Inbound destination | The trunk that rings when a call arrives for one of the connection's numbers. | `inbound_trunk_id` |
| Peers | Where Signals sends outbound calls: the SIP addresses of your carrier. | `peers` on create, then `/byoc/connections/{connection_id}/peers` |
| Numbers | The numbers your carrier holds for you, which this connection carries. | `POST /numbers/hosted` |
| Limits | How many calls run at once, how fast new calls start, and how long a call may last. | `ceilings` |
| Media | Which 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:

```bash
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](/sip-trunks/numbers-and-routing#route-numbers-to-a-trunk).
- Edits use `PATCH /byoc/connections/{connection_id}` with the connection's ETag in `If-Match`, as
  for trunks. See [Revisions and ETags](/sip-trunks/overview#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.

| Item | Value |
| --- | --- |
| Where to send calls | The connection's hostname, for example `airtel-direct.sip.trunk.pressone.co`. |
| Ports | SIP over UDP and TCP on 5060, and SIP over TLS on 5061. |
| Signals addresses | `signaling_nodes` and `media_cidrs` from [platform endpoints](/sip-trunks/overview#platform-endpoints), for your carrier's firewall. |
| Credentials | The 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:

```bash
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](/sip-trunks/numbers-and-routing#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:

| Field | What it does |
| --- | --- |
| `number_format` | How the dialled number is written: `e164_plus` (`+2348031234567`), `e164` (`2348031234567`) or `national` (`08031234567`). |
| `tech_prefix` | One to fifteen digits put before the dialled number, if your carrier asks for one. |
| `strip` | Leading digits removed from the dialled number, up to 14. |
| `identity_policy` | `from_only` sends the caller ID in `From`; `from_and_pai` also sends it in `P-Asserted-Identity`. |
| `privacy_passthrough` | `true` passes the caller's privacy request on to your carrier. |
| `media_security` | `rtp` 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:

| Reply | Meaning |
| --- | --- |
| `404 UNKNOWN_HOST` | The 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_PERMITTED` | The call came from an address that is not on the IP list, or the connection is disabled or does not take inbound calls. |
| `407` | The connection uses a password, and the carrier has not answered the challenge yet. |
| `403 AUTHENTICATION_FAILED` | The username or password is wrong. |
| `404 NUMBER_NOT_REGISTERED` | The dialled number is not imported on this connection. |
| `480 DESTINATION_UNAVAILABLE` | The 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](/sip-trunks/outbound-policies)
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.

## Related

- [Numbers and routing](/sip-trunks/numbers-and-routing) explains routes, which hosted numbers use
  too.
- [Authentication and security](/sip-trunks/authentication-and-security) covers TLS and encrypted
  media.
- [Carrier connections API reference](/api/signals/carrier-connections) and
  [Hosted numbers API reference](/api/signals/hosted-numbers)
