API reference / Get started
Quickstart
This page takes you from no key to a message on your own phone, and the result of that send in your hands. It takes about ten minutes.
Prefer to start from code? Clone the Drop Cowboy® repo on GitHub and run
examples/api/quickstart: one file, Node.js 20 or newer, nothing to install. It sends a ringless voicemail to your own number and tells you where to read the result. The same repo has the examples in Node.js, Python and C# and a Starter CRM built on Building Blocks.
1. Create an API key
In the dashboard, go to Developers > API keys and create a key. Copy the secret now, because it's shown once. Your account must be verified before you can create a key.
Put both values in environment variables. Every example in these docs uses them:
export DC_KEY="7f3c9a1e-5b2d-4e8f-a6c4-9d1b3e7f5a20"
export DC_SECRET="c8e2a4f6-1d3b-4a9c-8e7f-2b5d9a1c6e34"
Authentication covers scopes, OAuth and managing keys with the API.
2. Make your first call
Fetch your account to check the key works:
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" }
}
A 401 means the key or secret is wrong. Every response has this data and
meta shape. See Responses, errors and limits.
If you'd rather click than type, import the Postman collection and send the same request from Postman. See OpenAPI and Postman.
3. Subscribe to results
A send answers 202 before anything is sent, and its result arrives later on
a webhook. Create one before you send. Use any public HTTPS address where you
can read incoming requests, and list the result events you want in
event_types:
curl -X POST https://api-v2.dropcowboy.com/register/public/webhooks \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{ "hook_url": "https://hooks.example.com/dropcowboy", "event_types": ["contact.rvm.status", "contact.sms.status", "contact.email.status"] }'
| Event type | Results of |
|---|---|
contact.rvm.status |
Ringless voicemail, voice broadcasts and AI calls |
contact.sms.status |
Texts |
contact.email.status |
Webhooks are signed and retried, and one webhook covers every send. The
response includes a signing_secret. Store it, and use it to check that
deliveries came from Drop Cowboy. Add name to label the webhook, and create
more webhooks if you want separate URLs or secrets. To change a webhook's URL
or events later, update it. See
Verify the signature.
Send routes also accept a callback_url, for when each send needs its own
address. You don't need one here. See
callback_url.
4. Send to yourself
First, add your own phone number and email address on the Dialing rules page in the dashboard, as a test number and a test email address. Test numbers skip the contact frequency limit, so you can send to yourself as often as you like while you build. Calling hours still apply unless you turn on Allow Test Numbers to Bypass TCPA Hours on that page. To test a specific result, such as a busy line or a do-not-contact failure, send to a simulated number instead.
A phone send needs a phone line to send from, and a ringless voicemail needs an audio file. Look up their ids:
curl https://api-v2.dropcowboy.com/phone/public/lines \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
curl "https://api-v2.dropcowboy.com/media/public/media?limit=10" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
Send a ringless voicemail
Ringless voicemail delivers your recorded message directly to the contact's voicemail box.
curl -X POST https://api-v2.dropcowboy.com/rvm \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+13125550142",
"phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
"media_id": "1b7e3c9a-4d2f-4a8b-9e6c-7f2a1d5b3c80",
"foreign_id": "quickstart-1"
}'
{ "status": "queued", "message_id": "8e4a2c6f-9d1b-4f7e-b3a5-6c9e1f4d2b78" }
202 means the send was queued, not delivered. The result arrives on your
contact.rvm.status webhook. See Ringless voicemail for every
option, including spoken text instead of a file.
Send a text
The phone line must have an approved texting campaign.
curl -X POST https://api-v2.dropcowboy.com/sms \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+13125550142",
"phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
"body": "Hello from the Drop Cowboy quickstart. Reply STOP to opt out.",
"foreign_id": "quickstart-2"
}'
See Texts for pictures, templates and replies.
Send a voice broadcast
A voice broadcast calls the contact and plays a message, one for a person and
one for an answering machine. Pick a voice from GET /voice/public/voices.
curl -X POST https://api-v2.dropcowboy.com/voice-broadcast \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": "+13125550142",
"phone_line_id": "e2b6f9a3-5c1d-4e8b-a4f7-9c3e1b5d7a28",
"voice_id": "9c4e7a2f-1b8d-4f3e-a6c5-2d9b4e7f1a63",
"tts_on_speech": "Hi, this is a test call from the Drop Cowboy quickstart.",
"tts_on_beep": "Hi, this is a test message from the Drop Cowboy quickstart.",
"foreign_id": "quickstart-3"
}'
See Voice calls for key presses, transfers and AI calls.
Send an email
Email goes out from a sending mailbox on a verified domain. Find yours with
GET /domain/public/mailboxes.
curl -X POST https://api-v2.dropcowboy.com/email/public/email \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"to": [{ "address": "jordan@example.com", "name": "Jordan Rivera" }],
"mailbox_id": "c5f1a8d3-6e2b-4c9f-b1a7-8d4e2c6f9b35",
"subject": "Hello from the quickstart",
"html": "<p>Hi Jordan, this is a test email.</p>"
}'
{
"data": { "success": true },
"meta": { "request_id": "c2a6e8f4-3b9d-4c1e-8a7f-5d3b1e9c6a24" }
}
Unlike the phone sends, email answers once it's handed off. success: false
means nothing was sent. See Email.
5. Read the result
The result of a phone send arrives on your webhook like this:
{
"event_id": "d1f3a8e2-7c4b-4f9a-9d22-9c1e2f3a4b5c",
"event": "contact.rvm.status",
"event_at": 1774041600000,
"data": {
"contact_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
"drop_id": "6ae22fc9b41d3e0a7c5f9e21",
"campaign_type": "rvm",
"status": "success",
"reason": "",
"reason_code": 0,
"to": "+13125550142",
"from": "+12125550100",
"foreign_id": "quickstart-1"
}
}
statusissuccessorfailure.reason_codesays why. Outcomes lists every code and whether to retry.- Match results to your requests with
foreign_id.
To check a send from the dashboard, search its message_id in
Settings > API Logs. Status is whether it passed the checks made when it
arrived; Delivery is the later result. The same sends are under Campaigns
in the API entry (Show API send history is on by default). Add a
status webhook so each result is also pushed to your server.
6. If nothing arrives
Work through Troubleshooting. The usual causes are:
- Your webhook URL isn't publicly reachable over HTTPS, or doesn't answer
POSTwith2xx. - The key or secret on the send was wrong. That result (
3007) never fires a webhook. It arrives on the send'scallback_url, and Settings > API Logs lists the refused send when the key is yours. - The send was outside calling hours, so a voice send is held for later and
a text fails with
4011. A held voice send has no webhook until it goes out. To drop to your own phone after hours, turn on Allow Test Numbers to Bypass TCPA Hours on the Dialing rules page. See Test numbers. - The phone line has no approved texting campaign, so a text fails with
3029. - Your balance is empty, so the send fails with
3000. Check it withGET /campaign/public/balance.
Find the IDs you need
Every id a send asks for comes from a lookup route. Fetch them once and store them.
| You need | Route | Field |
|---|---|---|
| A phone line to send from | GET /phone/public/lines |
phone_line_id |
| An audio file | GET /media/public/media |
media_id |
| A voice, including your clones | GET /voice/public/voices |
voice_id |
| A contact | GET /contact/public/contacts |
contact_id |
| A contact list | GET /contact/public/lists |
list_ids |
| A registered brand | GET /automation/public/brands |
brand_id |
| An AI agent | GET /agents/public/agents |
agent_id |
| A sending mailbox | GET /domain/public/mailboxes |
mailbox_id |
| A saved template | GET /template/public/templates |
template_id |
Next steps
Follow a full guide
Each guide takes one task from setup to the result, with code in curl, Node.js, Python and C#. Start with Send a ringless voicemail on a retail plan, or browse every guide on the API reference.
Send to a whole list
A campaign sends to every contact on one or more lists in a single request. See Campaigns.
Place an AI call
An AI call puts one of your published AI agents on the phone with the contact. See Send an AI call.
Answer your phone with an AI agent
An AI receptionist is an agent that answers one of your phone lines. See Receptionist.
Go live
Before you send to real contacts, read Send lifecycle:
what a 202 means, how to retry without sending twice, and the rules every
send is checked against.
While Drop Cowboy provides tools to support compliance efforts, customers remain solely responsible for obtaining proper consent, maintaining opt-out lists, and complying with all federal and state telemarketing regulations. Consult with your legal counsel to ensure your specific use case and consent mechanisms comply with applicable laws.
This information is for educational purposes only and does not constitute legal advice. Regulations vary by jurisdiction and use case. Always consult with qualified legal counsel to ensure your specific practices comply with applicable federal and state laws.