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 with 400 and code byoc_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.

Code samples

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

List your numbers
curl https://api-v2.dropcowboy.com/phone/public/numbers \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Get a number
curl https://api-v2.dropcowboy.com/phone/public/numbers/%2B13125550142 \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Search for numbers to rent
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 }'
Add numbers
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"
  }'
Change a number
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 }'
List your phone lines
curl "https://api-v2.dropcowboy.com/phone/public/lines?type=voice" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
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"
Create a phone line
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" }'