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

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

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.

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.

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.

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.

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

For every other error, see Responses, errors and limits.