Bring your own carrier

Bring-your-own-carrier (BYOC) accounts send over a carrier account or SIP trunk they already have. The caller ID is your number at that carrier, and the audio can be a file you host yourself. Neither needs to exist in Drop Cowboy®.

Setup is two steps: connect the carrier once, then send as usual with caller_id and an audio source. To take inbound calls on those numbers, you also load them onto a phone line and point your trunk at Drop Cowboy.

audio_url is available on BYOC plans only and must be enabled by support. Contact support to enable it. If you're testing on a retail account before connecting your carrier, support can enable it for testing; while testing, voice sends go only to your test numbers. Otherwise, upload your file and send media_id, or use text to speech.

To build and test on a retail account first and go live here with the same request body, see Test on retail, then go live on BYOC.

To try calls and texts before you connect anything, use 555 test numbers. They're free and need no carrier.

For every way to use your numbers, with code in curl, Node.js and Python, see Use your own numbers on BYOC.

For a walk-through of one send with your own caller ID, see Send a ringless voicemail from your own caller ID. To let the platform choose the caller ID for each recipient, see Choose the caller ID automatically with phone lines.

How routing works

A send has no SIP route, trunk or host field. The route is part of the carrier connection. When you connect a carrier, Drop Cowboy builds the voice and ringless voicemail routes that point at its trunk, and every send goes out through them. To change where calls go, connect a different carrier or update the one you have. See Connect a carrier.

1. Connect your carrier

POST /integration/public/byoc/connect with the account:write scope. The credentials keys depend on the carrier:

provider credentials keys
twilio account_sid, auth_token
thinq account_id, username, account_token, tech_prefix (optional)
telnyx api_key
signalwire space_url, project_id, api_token
infobip base_url, api_key, service_address_name, service_address_street, service_address_city, service_address_state, service_address_zip
flowroute access_key, secret_key
plivo auth_id, auth_token
bandwidth account_id, username, password, site_id, application_id
vonage api_key, api_secret
sinch project_id, key_id, key_secret
custom carrier_name, sip_host, sip_port, username, password, tech_prefix (optional)

For thinq, the account_id and username are on My Profile in the Commio portal, and account_token is an API token you create under API, then Tokens, with every service turned on. Commio needs no password.

For infobip, base_url is your account's API host, such as your-subdomain.api.infobip.com. The API key needs the scopes message:send, inbound-message:read, sms:manage, mms:manage, rcs:manage, numbers:manage, calls:manage, callrouting:manage and account-management:manage. Infobip trusts your Dedicated IP, so it must be active first. Drop Cowboy creates the Infobip SIP trunk and call route. Infobip creates a SIP trunk only against a US service address (the place of primary use), so every service_address_* key is required: service_address_state is the two-letter state code and service_address_zip a 5-digit ZIP or ZIP+4. If your Infobip account already has that address, it is reused; otherwise it is added. A missing or malformed address fails with infobip-service-address-required.

Infobip voice finishes setting up about a minute after connect. Until then voice_status is provisioning in public_data and in GET /integration/public/byoc, then ready, or failed with the reason in voice_error. To retry, connect again with the same credentials and integration_id.

Use custom for a SIP trunk that isn't listed. sip_host is the trunk's hostname or IP address and sip_port is its port, usually 5060. Send username and password when the trunk uses credential authentication, and leave them out when it trusts your source IP. You can connect more than one account of the same carrier. Omit integration_id to add a connection; send it to update that connection. If the team has exactly one connection of that type and the account identifier matches (for example Twilio account_sid), a reconnect without integration_id updates it instead of creating another. Each connection may have a carrier_name. Results name the carrier each call was tried on, as described in Which carriers were tried. A team can have at most 10 connections of each carrier type.

Tech prefixes for carriers that trust your IP

Commio (ThinQ), and custom trunks with no username, recognize you by your Dedicated IP. Two connections of the same carrier send from the same IPs, so the carrier needs another way to tell them apart. That is the tech_prefix: digits Drop Cowboy puts in front of every number it dials on that connection, so the carrier can match the call to the right trunk.

  • Commio. The prefix is exactly 4 digits. Leave it out and Drop Cowboy picks one when this connection needs it to stand apart from another Commio connection. Send one to choose your own. Drop Cowboy sets up the Commio trunks with it, so there's nothing to change in the Commio portal.
  • custom. The prefix is 1 to 10 digits, with no + or #. Send it only if your carrier gave you one, and enter the same prefix on the carrier's side. If two IP-trusted connections point at the same sip_host, each one needs its own prefix.

Carriers that sign you in with a username and password, such as Twilio, don't need a prefix. Neither does Infobip, because each connection gets its own trunk. A connect that would leave two connections indistinguishable fails with tech-prefix-conflict, and a prefix in the wrong format fails with invalid-tech-prefix.

curl -X POST https://api-v2.dropcowboy.com/integration/public/byoc/connect \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "custom",
    "credentials": {
      "carrier_name": "Example Carrier",
      "sip_host": "sip.carrier.example",
      "sip_port": "5060",
      "username": "example-trunk-user",
      "password": "example-trunk-password"
    },
    "channels": 60,
    "cps": 2,
    "enabled": true,
    "default": true,
    "confirm_leave_retail": true
  }'
Field Type Required Description
provider string Yes One of the carriers in the table.
credentials object Yes The keys for that carrier.
channels integer No The most calls your carrier lets you run at once. Defaults to 20000, so send your carrier's real limit.
cps integer No Calls per second your carrier allows. Defaults to 1.
enabled boolean No Send true to send on this carrier. Defaults to false.
default boolean No Send true to make it your default carrier. Defaults to false.
confirm_leave_retail boolean Unless already on BYOC Send true to allow the plan change described below.

The response carries connected: true, the pool_id, and plan_switched.

The plan change

Connecting a carrier moves an account that isn't on a BYOC plan to one. That releases any phone numbers you rent from Drop Cowboy and changes your billing. Because an API key could do this by accident, the call fails with 400 confirm-leave-retail-required until you send confirm_leave_retail: true. Nothing changes on that failure. Accounts already on BYOC can leave the field out, and plan_switched is false for them.

Your phone lines stay. Once you load your own numbers onto a line, a send with that phone_line_id keeps working.

Check the connection

GET /integration/public/byoc lists the carriers on your account. The credentials are never returned.

2. Send a ringless voicemail

POST /rvm as described in Ringless voicemail, with the BYOC fields:

Field Type Required Description
caller_id string Yes Your number at the carrier, in E.164. It's shown exactly as given, and your carrier has to accept it as a caller ID.
audio_url string One audio option A public http(s) URL of an mp3 or wav file, up to 50 MB, fetched when the voicemail is sent. It must be enabled by support first. You can send media_id (see Signed upload) or tts_body with voice_id instead.
byoc.sti_orig_id string No The origination ID your carrier assigned for STIR/SHAKEN signing, as a UUID.
byoc.sti_attestation string No The attestation level for the call: A, B or C.

To show one specific caller_id, don't send phone_line_id. When both are present the phone line wins, and numbers that aren't in Drop Cowboy aren't on a line. If you've imported your numbers onto a phone line, send phone_line_id and no caller_id, and a number from the line is used. That body also works on retail, so it doesn't change when you move to BYOC.

curl -X POST https://api-v2.dropcowboy.com/rvm \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Idempotency-Key: 3b7e9d1a-6c4f-4a82-b5d0-8f1e2c7a9b46" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "caller_id": "+17735550188",
    "audio_url": "https://your-server.example.com/audio/appointment-reminder.mp3",
    "byoc": {
      "sti_orig_id": "c4a7e1d2-9b3f-4a68-8d05-2e7f6b1a9c34",
      "sti_attestation": "A"
    },
    "foreign_id": "order-1042",
    "callback_url": "https://your-server.example.com/dropcowboy/rvm-result"
  }'

The values are placeholders. Use your own number at the carrier, your own audio address, and the sti_orig_id and attestation your carrier gave you.

The route answers 202 and the result arrives on callback_url and the contact.rvm.status webhook. See Where results arrive. Try it on your own phone first, as in the Quickstart.

Which carriers were tried

The result also carries route_attempts, on contact.rvm.status, contact.rvm.receipt and callback_url. It lists each of your carriers the voicemail was offered to, oldest first, and what each one answered. The last entry decided the call. Use it to see why a carrier refused a call, such as a channel limit, a CPS limit or a timeout. It doesn't need a signed call.

Field Meaning
route_attempts The attempts. At most 15.
route_attempts_truncated true when some attempts were left out to keep the list small. The earliest attempts and the deciding one are always kept.

Each attempt:

Field Meaning
integration_id The carrier connection, the same integration_id as in GET /integration/public/byoc. null when the attempt can't be matched to a connection, for example one removed since.
provider The carrier type, such as thinq, twilio or custom
carrier_name The name of this connection. Defaults to the carrier type, then Twilio 2 and so on. null when integration_id is.
code The SIP response code, such as 200, 403, 486 or 503. 408 when the carrier never answered.
reason The SIP reason phrase, such as Service Unavailable
detail The carrier's own explanation from its Warning or Reason header, such as Channels Exceeded - Limit 10. null when it gave none or only repeated reason.
q850_cause The Q.850 cause from the carrier's Reason header, or null
timeout true when the carrier never answered
"route_attempts": [
  {
    "integration_id": "8f3e1a9c-2d4b-4e7a-9c1f-5b6a7c8d9e0f",
    "provider": "custom",
    "carrier_name": "Carrier East",
    "code": 503,
    "reason": "Service Unavailable",
    "detail": "Channels Exceeded - Limit 10",
    "q850_cause": 34,
    "timeout": false
  },
  {
    "integration_id": "d1f3a8e2-7c4b-4f9a-9d22-9c1e2f3a4b5c",
    "provider": "thinq",
    "carrier_name": "Commio",
    "code": 200,
    "reason": "OK",
    "detail": null,
    "q850_cause": null,
    "timeout": false
  }
],
"route_attempts_truncated": false

Both fields are sent together or not at all. They're left out when no attempt was recorded, for example on a call to an emergency number. Texts and live voice calls don't carry them.

Receive calls on your own numbers

Sending needs no number inventory. A caller_id that isn't in Drop Cowboy goes out as given. Receiving is different. When a contact calls back the number on their voicemail, the call reaches your carrier first, and Drop Cowboy only sees it if you set up both of these:

  1. Point the trunk at us. In your carrier's portal, send inbound calls for the number to sip.dropcowboy.com on port 5060, over UDP. If your carrier supports SRV records, use _sip._udp.sip.dropcowboy.com instead, which spreads calls across both of our regions and fails over between them. For Twilio, Telnyx, SignalWire, Infobip, Plivo, Bandwidth, Vonage, Sinch, Flowroute and Commio (ThinQ), connecting the carrier already sets this up and attaches the numbers you import. A custom trunk is set up by hand.
  2. Put the number on a phone line. The phone line decides what happens to the call: forward, queue, voicemail, an AI agent or whatever you set up. A number that isn't on a phone line has nowhere to go. See Phone numbers.

Load numbers you already own

POST /phone/public/numbers/import loads numbers you already hold at your carrier onto a phone line. It needs the numbers:write scope and a BYOC account. Any other account gets 403 with code byoc_required, because a number loaded here becomes a caller ID your account can send from. A BYOC account with no connected carrier gets 400 with code pool_required.

Field Type Required Description
phone_numbers array of strings Yes The numbers, in E.164, up to 5,000 per request. A value that isn't E.164 fails the whole request with code invalid_phone_numbers and names the values.
phone_line_id string No The phone line the numbers go on. Default: your default voice line. With neither, the request fails with code phone_line_required.
overwrite_routing boolean No A number already on your account keeps its routing unless this is true. Default: false.
iso_country string No Two-letter country code, when it can't be read from the numbers.
curl -X POST https://api-v2.dropcowboy.com/phone/public/numbers/import \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "phone_numbers": ["+13125550142", "+13125550143"] }'

The route answers 202 with a long_job_id. Poll GET /phone/public/numbers/import/{job_id} until status is completed or failed:

{
  "data": {
    "long_job_id": "1d5b9f3e-7a2c-4e8d-b6f1-3c7a9e5d2b84",
    "status": "completed",
    "result": { "total_rows": 2, "added": 2, "updated": 0, "invalid": 0, "conflicts": 0 },
    "error": null
  }
}

Drop Cowboy doesn't check with your carrier that you own the numbers, so load only numbers you hold. A number that another account already holds isn't taken. It's counted in conflicts, and the rest still load. Loading doesn't change anything at your carrier, so point the trunk at us as described above.

If you'd rather work in the dashboard, use Number Pools, from the actions menu of your carrier's pool: Import from Carrier (BYOC) lists the numbers on your carrier account and mirrors the ones you pick, and Import CSV to Phone Line reads them from a CSV.

Texting from a loaded number also needs a registered texting campaign. See Texts.

Why POST /phone/public/numbers/rent doesn't load them

On a BYOC account, that route buys the numbers from your connected carrier and puts them on a phone line. It doesn't load numbers you already own. Use POST /phone/public/numbers/import. To find numbers to buy, search first with POST /phone/public/numbers/available. See Search for numbers to rent.

Who can choose a caller ID

Only a BYOC account can send from a caller_id it names. Every other account sends from its own phone lines, and a caller_id in the request is ignored. Replying to a text with POST /phone/public/sms/reply needs a caller_id that's a number on your account, and a campaign's caller_id must be a number on your account too, unless the account is BYOC.

Disconnect a carrier

POST /integration/public/byoc/disconnect with the provider. See Disconnect a carrier.

Code samples

The requests from this page, ready to copy. Set DC_KEY and DC_SECRET to your API key pair first.

Tech prefixes for carriers that trust your IP
curl -X POST https://api-v2.dropcowboy.com/integration/public/byoc/connect \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "custom",
    "credentials": {
      "carrier_name": "Example Carrier",
      "sip_host": "sip.carrier.example",
      "sip_port": "5060",
      "username": "example-trunk-user",
      "password": "example-trunk-password"
    },
    "channels": 60,
    "cps": 2,
    "enabled": true,
    "default": true,
    "confirm_leave_retail": true
  }'
2. Send a ringless voicemail
curl -X POST https://api-v2.dropcowboy.com/rvm \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Idempotency-Key: 3b7e9d1a-6c4f-4a82-b5d0-8f1e2c7a9b46" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+13125550142",
    "caller_id": "+17735550188",
    "audio_url": "https://your-server.example.com/audio/appointment-reminder.mp3",
    "byoc": {
      "sti_orig_id": "c4a7e1d2-9b3f-4a68-8d05-2e7f6b1a9c34",
      "sti_attestation": "A"
    },
    "foreign_id": "order-1042",
    "callback_url": "https://your-server.example.com/dropcowboy/rvm-result"
  }'
Load numbers you already own
curl -X POST https://api-v2.dropcowboy.com/phone/public/numbers/import \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "phone_numbers": ["+13125550142", "+13125550143"] }'