API reference / Outreach
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 samesip_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:
- Point the trunk at us. In your carrier's portal, send inbound calls for
the number to
sip.dropcowboy.comon port 5060, over UDP. If your carrier supports SRV records, use_sip._udp.sip.dropcowboy.cominstead, 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. Acustomtrunk is set up by hand. - 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.