Skip to main content
POST
/
tasks
Create Task
curl --request POST \
  --url https://api.usecobalt.com/v1/tasks \
  --header 'Content-Type: application/json' \
  --header 'access_token: <api-key>' \
  --header 'client_id: <api-key>' \
  --header 'client_secret: <api-key>' \
  --data '
{
  "description": "<string>",
  "patient_mrn": "<string>",
  "subject": "<string>",
  "assignee_user_id": "<string>",
  "phone_call_type_id": "<string>",
  "notify_list": [
    "<string>"
  ]
}
'
{
  "success": true,
  "message": "<string>",
  "task_id": "<string>",
  "job_id": 123
}

Documentation Index

Fetch the complete documentation index at: https://docs.usecobalt.com/llms.txt

Use this file to discover all available pages before exploring further.

Depending on the EMR system connected to the account, additional fields beyond the base required fields may be required. If a conditionally required field is missing, the API will return a 400 error specifying the missing field.

​
Request Parameters

​
Required Fields

These fields are always required regardless of the connected EMR:
  • description (string, required): Task description/body content
  • patient_mrn (string, required): Medical Record Number (MRN) of the patient

​
Conditionally Required Fields

Depending on the connected EMR, some combination of the following fields will also be required:
  • subject (string, conditionally required): Task title/subject line
  • assignee_user_id (string, conditionally required): EMR user ID to assign the task to
  • phone_call_type_id (string, conditionally required): Identifier for the phone call type
  • notify_list (string[], optional): List of user identifiers to notify about the task. Must be an array of strings if provided.

​
Example Requests

curl -X POST https://api.usecobalt.com/v1/tasks \
-H 'Content-Type: application/json' \
-H 'client_id: ci_live_198908HJDKJSH98789OHKJL' \
-H 'client_secret: cs_live_9827hofdsklOYYHJLJh' \
-H 'access_token: 493JKLHIU98789hLKH9HHJH' \
-d '{
    "description": "Schedule patient follow-up appointment to review recent lab results and discuss treatment plan.",
    "patient_mrn": "MRN-12345",
    "subject": "Follow-up appointment needed",
    "assignee_user_id": "74196090-5faa-11e9-9562-e12f6a3ce827"
}'

​
Example Response

{
    "success": true,
    "message": "Task processing. A webhook event will be sent upon completion.",
    "task_id": "abc123def456789012345678",
    "job_id": 12345
}
The response includes:
  • task_id: Unique identifier for the created task record
  • job_id: Job execution identifier for tracking the async operation

​
Error Responses

​
Missing Required Field

If a required or conditionally required field is missing, the API returns a 400 with the specific field name: 
{
    "success": false,
    "message": "Missing required field: description"
}

​
User Not Found

{
    "success": false,
    "message": "User not found."
}

​
Webhook Notifications

When the task processing is complete, we will send a webhook to your registered endpoint. Here are examples of what those webhook payloads will look like:

​
Success

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gV",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2025-10-09T10:30:00Z",
    "type": "task.created",
    "job_id": "12345",
    "data": {
        "task_id": "abc123def456789012345678",
        "emr_task_id": "task_emr_internal_id",
        "subject": "Follow-up appointment needed",
        "description": "Schedule patient follow-up appointment to review recent lab results and discuss treatment plan.",
        "assignee_user_id": "74196090-5faa-11e9-9562-e12f6a3ce827",
        "patient_mrn": "MRN-12345"
    }
}

​
Failure

{
    "id": "evt_1J9X2q2eZvKYlo2CluR9g9gW",
    "access_token_reference_id": "user_1J9X2q2eZvKYlo2Cxyz",
    "object": "event",
    "created": "2025-10-09T10:35:00Z",
    "type": "task.failed",
    "job_id": "12345",
    "data": {
        "task_id": "abc123def456789012345678",
        "failure_reason": "Failed to create task"
    }
}

Authorizations

​
client_id
string
header
required
​
client_secret
string
header
required
​
access_token
string
header
required

Body

application/json
​
description
string
required

Task description/body content

​
patient_mrn
string
required

Medical Record Number (MRN) of the patient

​
subject
string

Task title/subject line. Conditionally required depending on the connected EMR.

​
assignee_user_id
string

EMR user ID to assign the task to. Conditionally required depending on the connected EMR.

​
phone_call_type_id
string

Identifier for the phone call type. Conditionally required depending on the connected EMR.

​
notify_list
string[]

List of user identifiers to notify about the task. Optional.

Response

Task queued successfully

​
success
boolean
​
message
string
​
task_id
string

Unique identifier for the created task record

​
job_id
integer

Job execution identifier for tracking the async operation