API reference / Phone and calls
Phone numbers
A phone number is a number you send from and receive calls and texts on. A phone line is the set of rules that decides what happens when someone calls one of your numbers: ring your team, play a menu, take a voicemail or hand the call to an AI agent. Each number is on one phone line, and one line can hold many numbers.
Sends take a phone_line_id rather than a number. The line's numbers become
the caller ID, and replies come back to that line. See
Sending basics. To build a line that an AI agent answers,
see AI receptionist, which also covers creating, changing
and deleting lines.
Routes
| Method | Route | Scope | What it does |
|---|---|---|---|
GET |
/phone/public/numbers |
numbers:read |
List your numbers |
GET |
/phone/public/numbers/{number} |
numbers:read |
Get one number |
PUT |
/phone/public/numbers/{number} |
numbers:write |
Change a number's settings |
POST |
/phone/public/numbers/available |
numbers:read |
Search for numbers to rent |
POST |
/phone/public/numbers/reputation |
numbers:read |
Check number reputation |
POST |
/phone/public/numbers/rent |
numbers:write |
Add numbers to your account |
POST |
/phone/public/numbers/import |
numbers:write |
Load numbers you already own (BYOC only) |
GET |
/phone/public/numbers/import/{job_id} |
numbers:read |
Check a number import |
GET |
/phone/public/lines |
numbers:read |
List your phone lines |
GET |
/phone/public/lines/{line_id} |
numbers:read |
Get one phone line |
POST |
/phone/public/lines |
numbers:write |
Create a phone line |
GET |
/phone/public/lines/{line_id}/numbers |
numbers:read |
List the numbers on a phone line |
POST |
/phone/public/lines/{line_id}/assign |
numbers:write |
Put a number on a phone line |
POST |
/phone/public/lines/{line_id}/default |
numbers:write |
Make a phone line the default |
List your numbers
Returns every number on your account in one response, plus your number limit.
curl https://api-v2.dropcowboy.com/phone/public/numbers \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"limits": { "used": 2, "sms_enabled": 2, "team_limit": 5 },
"numbers": [
{
"_id": "66f2b1c4e8a9d3f1a2b4c6db",
"phone_number": "+13125550142",
"name": "Main office",
"status": "ready",
"voice_ivr_id": "234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08",
"campaign_id": "b2c9d5fd-d33a-4310-ac79-dcad36fdeed8",
"brand_id": "1394ea8c-6362-4456-98d9-f688b587e733",
"sms_enabled": true,
"voice_enabled": true,
"is_byoc": false,
"country_iso": "US",
"state_iso": "IL",
"city": "Chicago",
"area_code": "312",
"created_at": 1757491200000
}
]
},
"meta": { "request_id": "e6d04536-d71f-4a07-89ca-4a9f8c713bc9" }
}
| Field | Description |
|---|---|
voice_ivr_id |
The phone line the number is on. |
campaign_id |
The texting campaign the number is registered to. See List texting campaigns. |
sms_enabled |
The number can carry texts. A US number also needs a registered texting campaign before carriers deliver from it; until then a send fails with sms_registration_required. |
status |
ready, or pending_payment until the number is paid for. |
limits.sms_enabled |
How many of your numbers are set up for both calls and texts. |
limits.team_limit |
How many numbers your plan allows. |
Get a number
Pass the number in E.164, with the + encoded as %2B. Digits without the
+ also work.
curl https://api-v2.dropcowboy.com/phone/public/numbers/%2B13125550142 \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
The response is one number, with the same fields as in the list.
Search for numbers to rent
Finds numbers you can add with POST /phone/public/numbers/rent. A search buys
nothing and changes nothing. All fields are optional.
| Field | Type | Required | Description |
|---|---|---|---|
country_iso |
string | No | Two-letter country code. Default US. |
pattern |
string | No | An area code, such as 312. Non-digits are dropped. On a bring-your-own-carrier account, a longer string of digits matches numbers that contain it. Leave it out to search the whole country. |
type |
string | No | local or tollfree. Default local. On an account that isn't BYOC, a toll-free area code in pattern, such as 888, picks tollfree for you. |
limit |
integer | No | The most numbers to return, from 1 to 100. Default 10. A carrier can return fewer. |
Other fields, such as services, are accepted and ignored. Results aren't
filtered by capability. Read features or capabilities on each one.
curl -X POST https://api-v2.dropcowboy.com/phone/public/numbers/available \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "country_iso": "US", "pattern": "312", "type": "local", "limit": 5 }'
What it searches depends on your account:
- Bring-your-own-carrier accounts search the live inventory of the carrier
you connected, so every result is a number that carrier can sell you. Search
works for Twilio, Commio (ThinQ) and Sinch. A Telnyx carrier answers with an
empty list. For any other carrier, buy the number at the carrier and load it
with
POST /phone/public/numbers/import. With no connected carrier the call fails with400and codebyoc_not_configured. - Other accounts search Drop Cowboy®'s shared inventory, and can rent from it only during the trial period.
The answer is always a list in data, whichever carrier answered. An empty list
means nothing matched. Every result has phone_number in E.164. The other
fields depend on where the result came from.
A Twilio carrier:
{
"data": [
{
"provider_id": "+13125550143",
"phone_number": "+13125550143",
"features": { "cnam": false, "sms": true, "mms": true, "voice": true, "e911": false },
"complaints": {
"fcc": { "consumer": { "all": 0, "recent": 0 } },
"youmail": { "risks": { "spam": null, "fraud": null, "unlawful": null } }
}
}
],
"meta": { "request_id": "e6d04536-d71f-4a07-89ca-4a9f8c713bc9" }
}
Shared inventory:
{
"data": [
{
"phone_number": "+13125550145",
"area_code": "312",
"city": "Chicago",
"iso_state": "IL",
"location_label": "Chicago, IL",
"match_type": "exact",
"fcc_complaint_count": 0,
"youmail_complaint_count": 0,
"reputation_status": "unknown"
}
],
"meta": { "request_id": "dbe41aa2-f3c6-4c84-af13-fcdeb14479be" }
}
| Field | Where | Description |
|---|---|---|
phone_number |
All | The number in E.164. Pass it to the rent route. |
provider_id |
Twilio, ThinQ | The number as your carrier names it. |
features |
Twilio, ThinQ | What the carrier says the number can do. Twilio reports voice, sms and mms. ThinQ reports voice and sms. |
complaints |
Twilio, ThinQ | FCC consumer complaints (all time and recent, the last year) and YouMail risks, so you can skip numbers other people reported. A risk is null when YouMail has no rating. |
network, carrier, match_type |
ThinQ | Where the number sits in the network, which carrier holds it, and how close it is to your area code. |
type, region, capabilities, monthly_cost, currency |
Sinch | Sinch's description of the number, with its monthly cost in currency. |
area_code, city, iso_state, location_label |
Shared | Where the number is. location_label reads Chicago, IL. |
match_type |
Shared | How close the number is to your area code: exact, same_state or other. |
fcc_complaint_count, youmail_complaint_count |
Shared | Complaints filed against the number. |
reputation_status |
Shared | unknown until a reputation check has run. |
Results carry no price. To rent what you find, see Add numbers.
Add numbers
Adds the numbers you name to your account. This route works on
bring-your-own-carrier accounts and on accounts in their trial period. On other
accounts, buy numbers in the dashboard. On a bring-your-own-carrier account it
buys the numbers from your connected carrier, so it can't load numbers you
already own. To load those, use POST /phone/public/numbers/import, described
in Bring your own carrier.
It works on BYOC accounts only.
| Field | Type | Required | Description |
|---|---|---|---|
numbers |
array of strings | Yes | The numbers to add, in E.164. Take them from a search. A single number string also works. |
voice_ivr_id |
string | No | Put the new numbers on this phone line. Default: your default phone line. |
curl -X POST https://api-v2.dropcowboy.com/phone/public/numbers/rent \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"numbers": ["+13125550142", "+13125550143"],
"voice_ivr_id": "234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08"
}'
{
"data": { "numbers": ["+13125550142", "+13125550143"] },
"meta": { "request_id": "dbe41aa2-f3c6-4c84-af13-fcdeb14479be" }
}
Each new number fires the number.provisioned webhook. See
Webhooks.
Change a number
PUT /phone/public/numbers/{number} changes one number's settings. Send only
the fields you want to change. A field you leave out keeps its value. Put the
number in the path in E.164. The leading + can be written as %2B.
| Field | Type | Description |
|---|---|---|
name |
string | A label for the number. |
voice_ivr_id |
string | Move the number to this phone line. It does the same as Put a number on a phone line. |
sms_enabled |
boolean | Turn texting on or off for the number. |
brand_id |
string or null | The brand the number sends under. Moving the number to a line sets it to the line's brand. null means your default brand. |
campaign_id |
string or null | The texting campaign the number sends under. |
fax |
boolean | Marks the number as a fax number. |
features |
object | Feature flags to store on the number. Replaces the object that was there. |
dni |
object or null | Call-tracking tags. Replaces the tags that were there, and null removes them. |
confirm_move |
boolean | true to move a number off another texting campaign when the line's campaign was imported from Twilio. |
curl -X PUT "https://api-v2.dropcowboy.com/phone/public/numbers/%2B13125550142" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "name": "Main office", "sms_enabled": true }'
{
"data": {},
"meta": { "request_id": "6b0a9f6e-6d1c-4f3e-b9a6-3d5a0f0e7c21" }
}
data is empty. When the request includes voice_ivr_id, it holds e911, as
in Put a number on a phone line. Read the
number with GET /phone/public/numbers/{number} to see the result. Every
change fires the number.updated webhook.
dni takes utm_source, utm_medium, utm_campaign, is_default and
region, which is east, central, west or national. Text values are
trimmed and lowercased. Only one number on a line can have is_default. Setting
it on a number clears it on the others.
The 911 callback number of a location can't be renamed or moved. That answers
400 with code e911_elin_locked.
List your phone lines
Returns every phone line in one response. A line's ivr_id is the
phone_line_id you pass on sends and campaigns.
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | No | Only lines of this type, for example voice. |
search_term |
string | No | Only lines whose name contains this text, ignoring case. |
statistics |
boolean | No | true to add sms_enabled_count and rcs_enabled_count to each line. |
curl "https://api-v2.dropcowboy.com/phone/public/lines?type=voice" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": [
{
"_id": "66f2b1c4e8a9d3f1a2b4c6dc",
"ivr_id": "234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08",
"team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
"type": "voice",
"name": "Main line",
"is_default": true,
"campaign_id": "b2c9d5fd-d33a-4310-ac79-dcad36fdeed8",
"brand_id": "1394ea8c-6362-4456-98d9-f688b587e733",
"rules": [
{ "start_rule": true, "end_rule": false, "action": "Queue", "action_data": {} }
],
"after_hour_rules": [],
"availability": null,
"rcs_enabled": false,
"created_at": 1757491200000,
"updated_at": 1759312800000
}
],
"meta": { "request_id": "ceeb5da8-09c2-47b5-98dd-f672bb92dc1f" }
}
rules, after_hour_rules and availability are explained in
AI receptionist.
Get a phone line
curl https://api-v2.dropcowboy.com/phone/public/lines/234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08 \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
The response is one line, with the same fields as in the list.
Create a phone line
Creates a line that you can put numbers on and send from. Its ivr_id is the
phone_line_id you pass on sends. To have the platform choose a number on it
for each recipient, see
Choose the caller ID automatically with phone lines (BYOC).
| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | A label for the line. Names aren't unique, so creating twice makes two lines. List with search_term first to check. |
type |
string | Yes | Send voice. |
rules |
array | No | What happens when someone calls a number on the line, during business hours. See AI receptionist. |
after_hour_rules |
array | No | The same, outside availability. |
availability |
object | No | The line's business hours: a time zone tz and seven days, Sunday first. See AI receptionist. |
campaign_id |
string | No | The registered texting campaign the line sends under. |
fax |
boolean | No | true for a fax line. Default false. |
The default field isn't read on create. The first line of a type becomes
the default for that type, and a line you create later doesn't take it over. To
change the default, see Make a phone line the default.
A line with no rules can be sent from. Add rules for calls to its numbers. A
rule with a Forward To or Forward + Voicemail action needs a verified
account. Without one the request answers 403.
curl -X POST https://api-v2.dropcowboy.com/phone/public/lines \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "name": "Local presence", "type": "voice" }'
{
"data": { "ivr_id": "234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08" },
"meta": { "request_id": "5d8f2b6a-3c1e-4a97-8b4d-7e9a1c3f5b20" }
}
data.ivr_id is the new line's id. Read the whole line with
Get a phone line.
List the numbers on a phone line
curl https://api-v2.dropcowboy.com/phone/public/lines/234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08/numbers \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
The answer is a list of numbers in data, each with the same fields as
GET /phone/public/numbers/{number}. Released numbers and shared trial numbers
are left out. The list isn't paged. A line_id that isn't one of your lines
gives an empty list, not 404. To check that a line exists, get it first.
Put a number on a phone line
Moves a number to this line. Calls to the number follow the line's rules from then on.
| Field | Type | Required | Description |
|---|---|---|---|
number |
string | Yes | The number, in E.164. |
confirm_move |
boolean | No | true to move a number off another texting campaign when the line's campaign was imported from Twilio. |
curl -X POST https://api-v2.dropcowboy.com/phone/public/lines/234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08/assign \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "number": "+13125550143" }'
{
"data": {
"e911": {
"old_location_id": null,
"new_location_id": "49df5f33-ef15-4256-ab61-736230539be3",
"rebound": true
}
},
"meta": { "request_id": "62aa3f5e-bd18-4468-9ee6-bb06d87c0999" }
}
e911 reports whether the number's 911 address changed to the one for this
line. The change fires the number.updated webhook.
Make a phone line the default
The default line takes the numbers you add without a voice_ivr_id. An account
has one default line for each line type. Making a line the default removes it
from the line that was the default before.
| Field | Type | Required | Description |
|---|---|---|---|
type |
string | Yes | The line's own type, as GET /phone/public/lines shows it, for example voice. |
curl -X POST https://api-v2.dropcowboy.com/phone/public/lines/234ecab5-1811-4c7d-a7a9-8c9ad9ca2e08/default \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "type": "voice" }'
data in the answer is empty. A line that isn't yours, or whose type isn't the
one you sent, answers 404 and the current default stays. A system route, such
as a 911 callback route, answers 400.
Errors
| Status | When | What to do |
|---|---|---|
400 |
use_cart_instead |
Buy numbers in the dashboard. |
400 |
e911_elin_locked, missing parameters or a system route as the default line. |
A 911 callback number can't be renamed or moved. For missing parameters, send the field the route needs. |
400 |
Please verify your identity. |
Finish identity verification in the dashboard, then try again. |
402 |
Your account has no funds or is past due. | Add funds, then try again. See Payment required. |
403 |
Maximum amount of numbers exceeded |
Release a number in the dashboard, or upgrade your plan. |
403 |
Verify your brand to use call forwarding rules. on create, because a rule forwards calls. |
Verify your brand in the dashboard, or use a rule that doesn't forward. |
403 |
us_identity_required |
US numbers need proof of US residence or a verified US business. Contact support. |
403 |
e911_team_location_required |
Add a team 911 address in the dashboard before adding US numbers. |
404 |
Phone number not found, number not found or Phone line not found. Nothing changes. |
Check the value with the list routes above. |
409 |
The number is registered to a different texting campaign than the line. | Put the number on a line that uses its campaign, or move it to the right campaign in the dashboard. For a campaign imported from Twilio, send confirm_move: true. |
For every other error, see Responses, errors and limits.