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.

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.

Code samples

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

Get account info
curl https://api-v2.dropcowboy.com/register/public/account \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Get your balance
curl https://api-v2.dropcowboy.com/campaign/public/balance \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
List users
curl "https://api-v2.dropcowboy.com/user/public/users?limit=50&skip=0" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Check Building Blocks readiness
curl https://api-v2.dropcowboy.com/register/public/integration-readiness \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Enable Building Blocks
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 }'
Use existing contact consent in widgets
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 }'
Get carrier status
curl https://api-v2.dropcowboy.com/integration/public/byoc \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Connect a 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
  }'