API reference / Account and reference
Account
These routes read your account details, your balance and your users. They also set up Building Blocks: check what's missing, switch it on, and connect your own carrier (BYOC). API keys are on Authentication.
Routes
| Method | Route | Scope | What it does |
|---|---|---|---|
GET |
/register/public/account |
balance:read |
Get account info |
GET |
/campaign/public/balance |
balance:read |
Get your balance |
GET |
/user/public/users |
contacts:read |
List users |
GET |
/register/public/integration-readiness |
balance:read |
Check Building Blocks readiness |
POST |
/register/public/building-blocks/enable |
account:write |
Enable Building Blocks |
POST |
/register/public/building-blocks/contact-consent |
account:write |
Use existing contact consent in widgets |
GET |
/integration/public/byoc |
balance:read |
Get carrier status |
POST |
/integration/public/byoc/connect |
account:write |
Connect a carrier |
POST |
/integration/public/byoc/disconnect |
account:write |
Disconnect a carrier |
Get account info
GET /register/public/account returns your account id, its owner and your
contact frequency limit.
curl https://api-v2.dropcowboy.com/register/public/account \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"team_id": "4e9a2c7f-1b5d-4f3e-8c6a-9d2b7e4f1a53",
"owner": {
"user_id": "auth0|65f1c2d3e4a5b6c7d8e9f0a1",
"first_name": "Jordan",
"last_name": "Rivera",
"email": "jordan@example.com"
},
"delivery_limits": {
"frequency": {
"max_attempts": 3,
"window_days": 3,
"window_ms": 259200000,
"source": "default"
}
}
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
| Field | Type | Description |
|---|---|---|
team_id |
string | Your account id. |
owner |
object | The account owner, or null if there is none. |
owner.user_id |
string | The owner's user id. It's an opaque string, not a UUID. |
owner.first_name, owner.last_name, owner.email |
string | The owner's name and email. |
delivery_limits.frequency.max_attempts |
integer | Most attempts to one phone number within the window. |
delivery_limits.frequency.window_days |
number | The window, in days. |
delivery_limits.frequency.window_ms |
integer | The window, in milliseconds. |
delivery_limits.frequency.source |
string | team if your account sets its own limit, default if it uses the platform default. |
You change the limit in the dashboard, not the API. See Contact frequency limit.
Get your balance
GET /campaign/public/balance returns your prepaid balance in US dollars.
One balance pays for every channel.
curl https://api-v2.dropcowboy.com/campaign/public/balance \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"balance": 250.75,
"reserved": 12.5,
"available": 238.25,
"recharge_amount": 100,
"recharge_threshold": 25,
"nag_no_funds_at": null
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
| Field | Type | Description |
|---|---|---|
balance |
number | Your current balance. |
reserved |
number | Held for sends that haven't settled yet. |
available |
number | What you can spend: balance minus reserved. |
recharge_amount |
number | What's charged automatically when the balance falls below recharge_threshold. |
recharge_threshold |
number | The balance that triggers an automatic recharge. |
nag_no_funds_at |
integer | When you were last told you were out of funds, in epoch milliseconds. null if never. |
An account that has never been funded gets an empty object in data.
Sends don't fail with 402 when the balance runs out. They fail later with
outcome 3000 (No Funds). See Balance.
List users
GET /user/public/users lists the users on your account.
curl "https://api-v2.dropcowboy.com/user/public/users?limit=50&skip=0" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer | No | Users per page, up to 100. Defaults to 50. |
skip |
integer | No | Users to skip, for paging. Defaults to 0. |
search_term |
string | No | Only users whose first name, last name or email starts with this. |
{
"data": {
"users": [
{
"_id": "7c2e9a4f-6b1d-4e8a-9f3c-2d5b8e1a7c46",
"user_id": "auth0|65f1c2d3e4a5b6c7d8e9f0a1",
"username": "jordan@example.com",
"team_id": "4e9a2c7f-1b5d-4f3e-8c6a-9d2b7e4f1a53",
"role_id": "3f7a1c9e-5d2b-4e8f-a6c3-9b1d7e4f2a85",
"status": "ENABLED",
"owner": true,
"identity": {
"first_name": "Jordan",
"last_name": "Rivera",
"email": "jordan@example.com"
},
"created_at": 1774041600000
}
],
"total_users": 1
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
| Field | Type | Description |
|---|---|---|
user_id |
string | The user's id. Pass this wherever another route asks for a user or owner. It's an opaque string, not a UUID. |
username |
string | The user's sign-in name. |
role_id |
string | The id of the user's role. |
status |
string | ENABLED or DISABLED. A disabled user can't sign in. |
owner |
boolean | true for the account owner. |
identity |
object | first_name, last_name and email. |
created_at |
integer | When the user was added, in epoch milliseconds. |
total_users |
integer | Users matching the request, across all pages. |
A field the user doesn't have comes back as null.
Check Building Blocks readiness
GET /register/public/integration-readiness tells you what's still missing
before Building Blocks widgets can place calls on your carrier.
curl https://api-v2.dropcowboy.com/register/public/integration-readiness \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"building_blocks_enabled": true,
"embed_resolve_contact_consent": false,
"byoc": {
"connected": true,
"providers": [
{
"provider": "twilio",
"integration_type": "twilio",
"integration_id": "2f8c4a6e-9b3d-4e1f-a7c5-6d2b9e4f1a38",
"enabled": true,
"default": true,
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
}
],
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
},
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61",
"numbers": {
"count": 1,
"items": [
{ "number_id": "8a3d6f1c-4e9b-4c2a-b7e5-1f8d3a6c9e24", "phone_number": "+13125550100", "name": "Main line" }
]
},
"voices": { "count": 2 },
"agents": { "count": 1, "published": 0 },
"funds": { "available": 238.25, "balance": 250.75, "reserved": 12.5, "funds_ok": true },
"allotment": {
"sms": { "remaining": 412, "cap": 500 }
},
"audio_url_allowed": true,
"test_numbers_only": false,
"test_numbers": ["+13125550142"],
"sandbox_only": false,
"sandbox_only_reason": null,
"embed_ready": true,
"next_actions": []
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
| Field | Type | Description |
|---|---|---|
embed_ready |
boolean | true when widgets can place calls: Building Blocks is on, a carrier is connected, and you have funds. |
next_actions |
array | What to do next, in order. Empty when embed_ready is true. |
building_blocks_enabled |
boolean | Building Blocks is on. It is on for every team billed for its own carrier (BYOC). |
embed_resolve_contact_consent |
boolean | Widgets may use a contact's existing consent. See Use existing contact consent in widgets. |
byoc |
object | Your carrier connections. Same shape as Get carrier status. |
pool_id |
string | Your carrier connection, or null. |
numbers |
object | count of your numbers and up to 50 of them in items. |
voices.count |
integer | Voices on your account. |
agents |
object | AI agents: count, and how many are published. |
funds |
object | balance, reserved, available, and funds_ok, which is true when you have balance or plan allowance left. |
allotment |
object | The included usage left on your plan, per product, as remaining and cap. Products are dialer_minutes, voice_ai_minutes, sms, rvm, detection_minutes, tts_characters, asr_minutes, mimic_voices and email. |
audio_url_allowed |
boolean | Ringless voicemail sends may use audio_url. Support enables it on BYOC plans; otherwise the send fails with 3014. |
test_numbers_only |
boolean | Testing mode: voice sends go only to your test numbers, and others fail with 3040. See Test on retail, then go live on BYOC. |
test_numbers |
array | Your test numbers in E.164, from the Dialing rules page. |
sandbox_only |
boolean | true when a dialer:webrtc or phone:hub site token minted now would only reach 555 test numbers. |
sandbox_only_reason |
string | Why: byoc_required or insufficient_balance. null when sandbox_only is false. |
Each next_actions value names one step:
| Value | What to do |
|---|---|
enable_building_blocks |
Enable Building Blocks. |
connect_byoc |
Connect a carrier. |
add_funds |
Add funds in the dashboard. |
rent_number |
Rent a number. See Phone numbers. |
create_agent |
Create an AI agent. See AI agents. |
publish_agent |
Publish your AI agent. See AI agents. |
Enable Building Blocks
POST /register/public/building-blocks/enable switches Building Blocks on.
If you aren't already on a bring-your-own-carrier plan, it also moves you to
the developer plan and releases every phone number you rent from
Drop Cowboy®. Confirm this by sending confirm_leave_retail: true.
curl -X POST https://api-v2.dropcowboy.com/register/public/building-blocks/enable \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "confirm_leave_retail": true }'
| Field | Type | Required | Description |
|---|---|---|---|
confirm_leave_retail |
boolean | Yes | Must be true. |
{
"data": {
"success": true,
"building_blocks_enabled": true,
"plan_switched": true,
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
| Field | Type | Description |
|---|---|---|
plan_switched |
boolean | true if your plan changed. false if you were already on a bring-your-own-carrier plan. |
pool_id |
string | Your carrier connection, or null if you haven't connected one. |
Use existing contact consent in widgets
POST /register/public/building-blocks/contact-consent turns on or off a
setting that lets widgets text or call back a contact who already gave consent
in Drop Cowboy. It's off by default. While it's off, every text or callback to
a US number from a widget needs a consent_id from Consent Capture.
curl -X POST https://api-v2.dropcowboy.com/register/public/building-blocks/contact-consent \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "enabled": true }'
| Field | Type | Required | Description |
|---|---|---|---|
enabled |
boolean | Yes | true to turn the setting on, false to turn it off. |
{
"data": {
"success": true,
"embed_resolve_contact_consent": true
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
When the setting is on and a widget sends contact_id without consent_id,
Drop Cowboy uses that contact's consent only if all of these are true:
- The contact is in your account.
- The number being texted or called is one of the contact's numbers.
- The contact has granted consent for that channel: texting consent for a text, calling consent for a callback.
- The contact hasn't opted out or replied STOP since that consent, and isn't on your Do Not Call list.
Otherwise the send fails with 403 and consent_required, the same as when
the setting is off. A contact imported with only a consent flag and no
recorded consent doesn't qualify. If a dashboard user calls this route, they
need permission to edit the Trust Center.
Get carrier status
GET /integration/public/byoc lists the carriers you've connected.
curl https://api-v2.dropcowboy.com/integration/public/byoc \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": {
"connected": true,
"providers": [
{
"provider": "twilio",
"integration_type": "twilio",
"integration_id": "2f8c4a6e-9b3d-4e1f-a7c5-6d2b9e4f1a38",
"enabled": true,
"default": true,
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
}
],
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
| Field | Type | Description |
|---|---|---|
connected |
boolean | true if at least one carrier is connected. |
providers |
array | One entry per connected carrier: its type in provider, optional carrier_name, whether it's enabled and the default, and its pool_id. You can have more than one entry of the same provider. |
pool_id |
string | Your carrier connection, or null. |
Connect a carrier
POST /integration/public/byoc/connect connects your account at a carrier
so calls and texts go through it. One call checks the credentials with the
carrier, builds the voice and ringless voicemail routes that point at its
trunk, saves the connection and moves the account to a BYOC plan. Sends don't
take a route field: they use the connected carrier. For the whole flow, from
connecting to sending from your own number, see
Bring your own carrier.
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": "twilio",
"credentials": {
"account_sid": "<your Twilio account SID>",
"auth_token": "<your Twilio auth token>"
},
"channels": 60,
"cps": 5,
"enabled": true,
"default": true,
"confirm_leave_retail": true
}'
| Field | Type | Required | Description |
|---|---|---|---|
provider |
string | Yes | twilio, thinq, telnyx, signalwire, infobip, plivo, bandwidth, vonage, sinch, flowroute or custom. |
credentials |
object | Yes | Your credentials at the carrier. The keys depend on provider; see the table in Bring your own carrier. Every type may include carrier_name. custom also takes sip_host, sip_port, username and password. |
integration_id |
string | No | Update this connection. Omit it to add another connection of the same carrier. If the team has exactly one connection of that type and the account identifier matches, a reconnect without integration_id updates it. |
enabled |
boolean | No | Send true to use this carrier. Defaults to false. |
default |
boolean | No | Send true to make this your default carrier. Defaults to false. |
channels |
integer | No | The most calls your carrier lets you run at once. Defaults to 20000. |
cps |
integer | No | Calls per second your carrier allows. Defaults to 1. |
confirm_leave_retail |
boolean | Unless already on BYOC | Send true to allow moving the account to a BYOC plan. That releases any phone numbers you rent from Drop Cowboy and changes billing. Without it the call fails with 400 confirm-leave-retail-required and nothing changes. |
{
"data": {
"connected": true,
"provider": "twilio",
"integration_type": "twilio",
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61",
"plan_switched": true,
"public_data": {
"enabled": true,
"default": true,
"pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
}
},
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
plan_switched is false when the account was already on a BYOC plan.
Connecting the same carrier again updates its settings.
| Status and code | What to do |
|---|---|
400 unknown-provider |
Send one of the listed provider values. |
400 missing-credentials |
Send credentials as an object. |
400 invalid-credentials |
The carrier rejected them. Check the keys and values. |
400 signalwire-missing-scopes or infobip-missing-scopes |
The token or API key lacks scopes, listed in details.missing_scopes. Add them at the carrier and send the request again. |
400 confirm-leave-retail-required |
Send confirm_leave_retail: true if you accept the plan change. |
502 plan-switch-failed |
The carrier was saved but the plan change didn't finish. Send the same request again. |
Disconnect a carrier
POST /integration/public/byoc/disconnect removes a carrier connection.
curl -X POST https://api-v2.dropcowboy.com/integration/public/byoc/disconnect \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "provider": "twilio" }'
| Field | Type | Required | Description |
|---|---|---|---|
provider |
string | Yes | The carrier type to disconnect. |
integration_id |
string | When more than one of that type | The connection to remove. Required when the team has more than one connection of that provider. |
{
"data": { "disconnected": true, "provider": "twilio", "integration_type": "twilio" },
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
Errors
| Status | When | What to do |
|---|---|---|
400 |
confirm_leave_retail isn't true, or provider isn't one of the listed carriers |
Fix the field named in detail |
403 |
The credential lacks the route's scope | Use a credential with that scope |
404 |
The account wasn't found | Check the credential belongs to the right account |
Errors use the format in Responses, errors and limits.
BYOC customers connect their own carrier accounts (Twilio, Bandwidth, etc.) to the Drop Cowboy platform. Customers are responsible for their carrier relationship, billing, and compliance with carrier terms of service. Drop Cowboy does not mark up or bill for carrier services. Message delivery and carrier connectivity depend on the customer's carrier account status and settings.