Inbox Tasks

Inbox Tasks are the items in your team's shared inbox. Drop Cowboy® adds one when a contact calls, texts, emails, leaves a voicemail or fills in a form. Use these routes to add your own follow-ups, assign items to a teammate, and close them when they're handled. Each task belongs to one contact.

Tasks fire the task.opened, task.assigned and task.closed webhooks. See Webhooks.

Routes

List tasks

Returns tasks oldest first. With no limit, every match is returned, so pass one.

curl "https://api-v2.dropcowboy.com/task/public/tasks?status=open&sort=desc&limit=25" \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

{
  "data": {
    "tasks": [
      {
        "task_id": "2d8d7e53-6427-446e-a1bd-a4ef8930f46c",
        "contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
        "task_type": "sms",
        "direction": "inbound",
        "status": "open",
        "urgent": false,
        "unread": true,
        "assigned_to": "fa933d82-485f-43b0-80ab-860121f06980",
        "assigned_type": "user",
        "assigned_at": 1759313000000,
        "created_at": 1759312800000,
        "preview_info": {
          "task_date": 1759312800000,
          "task_contact": "Jordan Lee",
          "task_content": "Can we move my appointment to Friday?"
        },
        "contact": {
          "contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
          "first_name": "Jordan",
          "last_name": "Lee",
          "main_phone": "+13125550118"
        }
      }
    ]
  },
  "meta": { "request_id": "a1e5ebaf-1765-4ea7-940c-0bcd44e79e68" }
}

The list has no total. Keep paging with skip until a page comes back with fewer than limit tasks. Timestamps are epoch milliseconds.

Each task also carries the item it came from, such as call, sms, fax or call_recording, and a last_record with its latest activity.

Get a task

Returns one task in the same shape as List tasks, or 404 when no task on your account has that task_id.

curl https://api-v2.dropcowboy.com/task/public/tasks/2d8d7e53-6427-446e-a1bd-a4ef8930f46c \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET"

Create a task

Adds an item to the inbox for a contact. The response is 201 with the new task.

curl -X POST https://api-v2.dropcowboy.com/task/public/tasks \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
    "task_type": "follow_up",
    "assigned_to": "fa933d82-485f-43b0-80ab-860121f06980",
    "assigned_type": "user"
  }'

{
  "data": {
    "_id": "66f2b1c4e8a9d3f1a2b4c6de",
    "task_id": "0ada17a0-c1db-4201-b5c7-85137c3738c0",
    "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
    "contact_id": "487d8607-e415-4d90-a1e1-f9c1a746e0a1",
    "task_type": "follow_up",
    "status": "open",
    "unread": true,
    "urgent": false,
    "priority": 0,
    "assigned_to": "fa933d82-485f-43b0-80ab-860121f06980",
    "assigned_type": "user",
    "created_at": 1759312800000,
    "created_by": "bcce25c4-6b8e-43d8-a1cb-689ddc6bb984",
    "updated_at": 1759312800000,
    "closed_at": null,
    "preview_info": {
      "task_date": 1759312800000,
      "task_contact": "Jordan Lee",
      "task_subject": "Follow-up Reminder",
      "subject": "Follow-up Reminder"
    }
  },
  "meta": { "request_id": "dc590416-d213-41d4-8d10-a9404b031adc" }
}

The response is the whole task. Some fields are left out here.

Assign a task or mark it urgent

Send only the fields you want to change. To open, snooze or close the task, use Open, snooze or close a task instead.

curl -X PUT https://api-v2.dropcowboy.com/task/public/tasks/0ada17a0-c1db-4201-b5c7-85137c3738c0 \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "assigned_to": "bcce25c4-6b8e-43d8-a1cb-689ddc6bb984",
    "assigned_type": "user",
    "urgent": true
  }'

{
  "data": {
    "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
    "user_id": "fa933d82-485f-43b0-80ab-860121f06980",
    "task_id": "0ada17a0-c1db-4201-b5c7-85137c3738c0",
    "urgent": true,
    "assigned_to": "bcce25c4-6b8e-43d8-a1cb-689ddc6bb984",
    "assigned_type": "user"
  },
  "meta": { "request_id": "2f1391f7-14b1-4435-9863-e0ef72382c72" }
}

The response echoes the change you sent, not the whole task. Assigning fires task.assigned.

Open, snooze or close a task

curl -X PUT https://api-v2.dropcowboy.com/task/public/tasks/0ada17a0-c1db-4201-b5c7-85137c3738c0/status \
  -H "x-key: $DC_KEY" -H "x-secret: $DC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "status": "snoozed", "snoozed_until": "2026-10-05T14:00:00Z" }'

{
  "data": {
    "team_id": "cd5cd773-4617-4b28-854d-d3adc74c96d5",
    "user_id": "fa933d82-485f-43b0-80ab-860121f06980",
    "task_id": "0ada17a0-c1db-4201-b5c7-85137c3738c0",
    "status": "snoozed",
    "snoozed_until": "2026-10-05T14:00:00Z"
  },
  "meta": { "request_id": "1f96d605-ea75-4c23-a071-93dc9208980f" }
}

Each change is recorded on the task's timeline. Closing a task marks it read and fires task.closed. A snoozed task reopens at snoozed_until.

Errors

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