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
`POST`	`/phone/public/numbers/rent`	`numbers:write`	Add numbers to your account
`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/{line_id}/assign`	`numbers:write`	Put a number on a phone line

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.
`status`	`ready`, or `pending_payment` until the number is paid for.
`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.

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.

Field	Type	Required	Description
`numbers`	array of strings	Yes	The numbers to add, in E.164.
`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.

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.

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.

Errors

Status	When	What to do
`400`	`use_cart_instead`	Buy numbers in the dashboard.
`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`	`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.