API reference / Work management
Automation
Use these routes when you build an integration or a no-code automation: they fill dropdowns with your brands, texting campaigns and send outcome codes, and they find or create a contact from just a phone number or email.
For full contact management, see Contacts and Contact lists. To pick a voice for text to speech, see Pick a voice.
Routes
| Method | Route | Scope | What it does |
|---|---|---|---|
GET |
/automation/public/brands |
contacts:read |
List brands |
GET |
/automation/public/pools |
numbers:read |
List texting campaigns |
GET |
/automation/public/dispositions |
contacts:read |
List outcome codes |
POST |
/automation/public/contacts |
contacts:write |
Create a contact |
POST |
/automation/public/contacts/find-or-create |
contacts:write |
Find or create a contact |
PUT |
/automation/public/contacts/list |
lists:write |
Add or remove a contact on a list |
List brands
Returns your registered texting brands, each with its texting campaigns, in
one response. Pass a brand's brand_id on campaigns and
pipelines to choose which brand they use.
curl https://api-v2.dropcowboy.com/automation/public/brands \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": [
{
"team_id": "4f3d2a8e-6c1b-4b7e-9a2d-8e5f1c3b7a90",
"brand_id": "8d1e6f2a-3b7c-4e9d-a5f1-2c8b4e6d9a03",
"company_name": "Example Realty LLC",
"dba_name": "Example Realty",
"registered": true,
"identity_status": "VERIFIED",
"opt_in_flow": "Customers opt in on the contact form at https://example.com/contact.",
"api_allowed": true,
"is_default": true,
"ucaas_campaigns": [],
"bulk_campaigns": [
{
"pool_id": "b6a2e9f4-1d3c-4a8b-9e7f-5c2d8a1b4e63",
"name": "Listing alerts",
"use_case": "MARKETING",
"registered": true,
"shared_10DLC": false
}
]
}
],
"meta": { "request_id": "6e9b3f1a-2c4d-4a7e-8b5f-9d1c3e7a2b40" }
}
| Field | Description |
|---|---|
is_default |
true for the brand used when a send doesn't name one. |
api_allowed |
true when the brand can send through the API. |
ucaas_campaigns |
The brand's campaigns with use case UCAAS_LOW or UCAAS_HIGH. |
bulk_campaigns |
The brand's other campaigns. Campaigns may also carry unified_mno_data, the carriers' review results. |
List texting campaigns
Returns your texting (10DLC) campaigns, registered or not, in one response.
A campaign's pool_id is the campaign_id shown on
phone numbers and phone lines.
| Field | Type | Required | Description |
|---|---|---|---|
search_term |
string | No | Only campaigns whose name contains this text. |
limit |
integer | No | Maximum campaigns to return. Default: all. |
curl "https://api-v2.dropcowboy.com/automation/public/pools?search_term=listing" \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": [
{
"pool_id": "b6a2e9f4-1d3c-4a8b-9e7f-5c2d8a1b4e63",
"name": "Listing alerts",
"use_case": "MARKETING",
"registered": true,
"shared_10DLC": false
}
],
"meta": { "request_id": "2d7c9a4e-5b1f-4e3a-8c6d-1f9b2e4a7c58" }
}
List outcome codes
Returns every outcome code a send can end with, as a fixed list. Use it to map
the reason_code on a send result to a label. Outcomes and what to do
explains each code.
curl https://api-v2.dropcowboy.com/automation/public/dispositions \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"
{
"data": [
{ "code": 0, "label": "Success", "category": "success" },
{ "code": 1000, "label": "Pending", "category": "pending" },
{ "code": 3001, "label": "Audio file not valid", "category": "config-error" },
{ "code": 4000, "label": "VoiceMail Not Detected", "category": "delivery-failed" }
],
"meta": { "request_id": "9a4e1c7b-3d2f-4b8a-a6e5-7c1d9f3b2e84" }
}
category is one of success, pending, config-error, delivery-failed,
email-issue, carrier-issue or other.
Create a contact
Creates a contact, or returns the one that already has this email or phone
number. The response is 201.
| Field | Type | Required | Description |
|---|---|---|---|
phone_number |
string | No | Phone number in E.164 format. |
email |
string | No | Email address. |
first_name |
string | No | First name. |
last_name |
string | No | Last name. |
Send at least one of phone_number, email or first_name. With only a name,
a new contact is created every time. Matching works as described in
Find or create a contact.
curl -X POST https://api-v2.dropcowboy.com/automation/public/contacts \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+13125550142",
"first_name": "Jane",
"last_name": "Doe",
"email": "jane@example.com"
}'
{
"data": {
"status": "success",
"contact_id": "3c8f1e6a-9b2d-4d7e-a4f3-6e1b8c2d9a57",
"created": true
},
"meta": { "request_id": "7b2e5d9c-1a4f-4c6b-9e3d-2f8a5c1b7e06" }
}
created is false when an existing contact matched.
Find or create a contact
Looks up a contact by email or phone number and creates one if none matches. You can also look up without creating, update the match, and add the contact to a list in the same call.
| Field | Type | Required | Description |
|---|---|---|---|
phone_number |
string | One of these | Phone number in E.164 format. |
email |
string | One of these | Email address. |
first_name |
string | No | First name, set on a new contact. |
last_name |
string | No | Last name, set on a new contact. |
list_id |
string | No | A contact list to add the contact to. |
create |
boolean | No | false to look up only, without creating. Default true. |
update_on_match |
boolean | No | true to overwrite a matched contact's name, email and phone with the values you send. Default false. |
Send the email when you have it: a contact with that email always matches. A phone number on its own matches any contact that has that number. With both, a contact matches only when its email agrees, so one person's phone number can't pull in another person's contact. Otherwise a new contact is created.
curl -X POST https://api-v2.dropcowboy.com/automation/public/contacts/find-or-create \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"email": "jane@example.com",
"phone_number": "+13125550142",
"first_name": "Jane",
"list_id": "5e2a8c1f-7d4b-4a9e-b3c6-8f1d2e7a4b95"
}'
{
"data": {
"status": "success",
"contact_id": "3c8f1e6a-9b2d-4d7e-a4f3-6e1b8c2d9a57",
"created": false,
"added_to_list": true
},
"meta": { "request_id": "1f6d3b8e-4a2c-4e9b-8d7a-5c3e1b9f2a68" }
}
added_to_list is false when you sent no list_id or the contact couldn't
be added to the list. The rest of the call still succeeds.
Add or remove a contact on a list
Adds a contact to a list, or removes it, identifying the contact by
contact_id, phone number or email.
| Field | Type | Required | Description |
|---|---|---|---|
list_id |
string | Yes | The contact list. |
contact_id |
string | One of these | The contact's id. |
phone_number |
string | One of these | The contact's main phone, in E.164 format. Must match exactly. |
email |
string | One of these | The contact's email. Must match exactly. |
action |
string | No | add (default) or remove_list to take the contact off the list. Any other value returns 400. |
If you send both phone_number and email, the contact must match both.
curl -X PUT https://api-v2.dropcowboy.com/automation/public/contacts/list \
-H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+13125550142",
"list_id": "5e2a8c1f-7d4b-4a9e-b3c6-8f1d2e7a4b95"
}'
{
"data": { "status": "success" },
"meta": { "request_id": "8c3a6e1d-2b9f-4d5a-a7e4-3b1c9d6f2e75" }
}
A contact_id isn't checked: an id that isn't on your account still returns
success and changes nothing.
Errors
| Status | When | What to do |
|---|---|---|
400 |
missing parameters: no identifier was sent, or list_id is missing. |
Send the required fields for the route. |
404 |
Contact not found: no contact matched, with create: false or on the list route. |
Check the phone number or email, or create the contact. |
For every other error, see Responses, errors and limits.
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.