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

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" }
}

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" }
}

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"

{
  "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" }
}

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": {
    "force_byoc": true,
    "building_blocks_enabled": true,
    "usage_plan": "usage-plan-builder",
    "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 }
    },
    "embed_ready": true,
    "next_actions": []
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

Each next_actions value names one step:

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 }'

{
  "data": {
    "success": true,
    "building_blocks_enabled": true,
    "plan_switched": true,
    "plan_id": "usage-plan-builder",
    "pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

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" }
}

Connect a carrier

POST /integration/public/byoc/connect connects your account at a carrier so calls and texts go through it.

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>"
    },
    "enabled": true,
    "default": true
  }'

{
  "data": {
    "connected": true,
    "provider": "twilio",
    "integration_type": "twilio",
    "pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61",
    "public_data": {
      "enabled": true,
      "default": true,
      "pool_id": "6e1f3a5c-9b2d-4c8e-a7f1-3d5b9c2e4a61"
    }
  },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

Connecting the same carrier again updates its settings.

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" }'

{
  "data": { "disconnected": true, "provider": "twilio", "integration_type": "twilio" },
  "meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}

Errors

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.