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 '
{
"patient_mrn": "12345",
"description": "Call patient about lab results",
"subject": "<string>",
"assignee_user_id": "<string>",
"phone_call_type_id": "<string>",
"notify_list": [
"<string>"
],
"location_id": "<string>",
"task_type": "<string>",
"details": "<string>",
"assigned_to": "<string>",
"facility_id": "<string>",
"due_date": "<string>",
"start_date": "<string>",
"callback_urls": [
"<string>"
]
}
'import requests
url = "https://api.usecobalt.com/v1/tasks"
payload = {
"patient_mrn": "12345",
"description": "Call patient about lab results",
"subject": "<string>",
"assignee_user_id": "<string>",
"phone_call_type_id": "<string>",
"notify_list": ["<string>"],
"location_id": "<string>",
"task_type": "<string>",
"details": "<string>",
"assigned_to": "<string>",
"facility_id": "<string>",
"due_date": "<string>",
"start_date": "<string>",
"callback_urls": ["<string>"]
}
headers = {
"client_id": "<api-key>",
"client_secret": "<api-key>",
"access_token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
client_id: '<api-key>',
client_secret: '<api-key>',
access_token: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
patient_mrn: '12345',
description: 'Call patient about lab results',
subject: '<string>',
assignee_user_id: '<string>',
phone_call_type_id: '<string>',
notify_list: ['<string>'],
location_id: '<string>',
task_type: '<string>',
details: '<string>',
assigned_to: '<string>',
facility_id: '<string>',
due_date: '<string>',
start_date: '<string>',
callback_urls: ['<string>']
})
};
fetch('https://api.usecobalt.com/v1/tasks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usecobalt.com/v1/tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'patient_mrn' => '12345',
'description' => 'Call patient about lab results',
'subject' => '<string>',
'assignee_user_id' => '<string>',
'phone_call_type_id' => '<string>',
'notify_list' => [
'<string>'
],
'location_id' => '<string>',
'task_type' => '<string>',
'details' => '<string>',
'assigned_to' => '<string>',
'facility_id' => '<string>',
'due_date' => '<string>',
'start_date' => '<string>',
'callback_urls' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"access_token: <api-key>",
"client_id: <api-key>",
"client_secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.usecobalt.com/v1/tasks"
payload := strings.NewReader("{\n \"patient_mrn\": \"12345\",\n \"description\": \"Call patient about lab results\",\n \"subject\": \"<string>\",\n \"assignee_user_id\": \"<string>\",\n \"phone_call_type_id\": \"<string>\",\n \"notify_list\": [\n \"<string>\"\n ],\n \"location_id\": \"<string>\",\n \"task_type\": \"<string>\",\n \"details\": \"<string>\",\n \"assigned_to\": \"<string>\",\n \"facility_id\": \"<string>\",\n \"due_date\": \"<string>\",\n \"start_date\": \"<string>\",\n \"callback_urls\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client_id", "<api-key>")
req.Header.Add("client_secret", "<api-key>")
req.Header.Add("access_token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/tasks")
.header("client_id", "<api-key>")
.header("client_secret", "<api-key>")
.header("access_token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"patient_mrn\": \"12345\",\n \"description\": \"Call patient about lab results\",\n \"subject\": \"<string>\",\n \"assignee_user_id\": \"<string>\",\n \"phone_call_type_id\": \"<string>\",\n \"notify_list\": [\n \"<string>\"\n ],\n \"location_id\": \"<string>\",\n \"task_type\": \"<string>\",\n \"details\": \"<string>\",\n \"assigned_to\": \"<string>\",\n \"facility_id\": \"<string>\",\n \"due_date\": \"<string>\",\n \"start_date\": \"<string>\",\n \"callback_urls\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecobalt.com/v1/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"patient_mrn\": \"12345\",\n \"description\": \"Call patient about lab results\",\n \"subject\": \"<string>\",\n \"assignee_user_id\": \"<string>\",\n \"phone_call_type_id\": \"<string>\",\n \"notify_list\": [\n \"<string>\"\n ],\n \"location_id\": \"<string>\",\n \"task_type\": \"<string>\",\n \"details\": \"<string>\",\n \"assigned_to\": \"<string>\",\n \"facility_id\": \"<string>\",\n \"due_date\": \"<string>\",\n \"start_date\": \"<string>\",\n \"callback_urls\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"task_id": "<string>",
"job_id": 123
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}Create Task
Creates a task in the provider’s EMR system.
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 '
{
"patient_mrn": "12345",
"description": "Call patient about lab results",
"subject": "<string>",
"assignee_user_id": "<string>",
"phone_call_type_id": "<string>",
"notify_list": [
"<string>"
],
"location_id": "<string>",
"task_type": "<string>",
"details": "<string>",
"assigned_to": "<string>",
"facility_id": "<string>",
"due_date": "<string>",
"start_date": "<string>",
"callback_urls": [
"<string>"
]
}
'import requests
url = "https://api.usecobalt.com/v1/tasks"
payload = {
"patient_mrn": "12345",
"description": "Call patient about lab results",
"subject": "<string>",
"assignee_user_id": "<string>",
"phone_call_type_id": "<string>",
"notify_list": ["<string>"],
"location_id": "<string>",
"task_type": "<string>",
"details": "<string>",
"assigned_to": "<string>",
"facility_id": "<string>",
"due_date": "<string>",
"start_date": "<string>",
"callback_urls": ["<string>"]
}
headers = {
"client_id": "<api-key>",
"client_secret": "<api-key>",
"access_token": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
client_id: '<api-key>',
client_secret: '<api-key>',
access_token: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
patient_mrn: '12345',
description: 'Call patient about lab results',
subject: '<string>',
assignee_user_id: '<string>',
phone_call_type_id: '<string>',
notify_list: ['<string>'],
location_id: '<string>',
task_type: '<string>',
details: '<string>',
assigned_to: '<string>',
facility_id: '<string>',
due_date: '<string>',
start_date: '<string>',
callback_urls: ['<string>']
})
};
fetch('https://api.usecobalt.com/v1/tasks', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.usecobalt.com/v1/tasks",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'patient_mrn' => '12345',
'description' => 'Call patient about lab results',
'subject' => '<string>',
'assignee_user_id' => '<string>',
'phone_call_type_id' => '<string>',
'notify_list' => [
'<string>'
],
'location_id' => '<string>',
'task_type' => '<string>',
'details' => '<string>',
'assigned_to' => '<string>',
'facility_id' => '<string>',
'due_date' => '<string>',
'start_date' => '<string>',
'callback_urls' => [
'<string>'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"access_token: <api-key>",
"client_id: <api-key>",
"client_secret: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.usecobalt.com/v1/tasks"
payload := strings.NewReader("{\n \"patient_mrn\": \"12345\",\n \"description\": \"Call patient about lab results\",\n \"subject\": \"<string>\",\n \"assignee_user_id\": \"<string>\",\n \"phone_call_type_id\": \"<string>\",\n \"notify_list\": [\n \"<string>\"\n ],\n \"location_id\": \"<string>\",\n \"task_type\": \"<string>\",\n \"details\": \"<string>\",\n \"assigned_to\": \"<string>\",\n \"facility_id\": \"<string>\",\n \"due_date\": \"<string>\",\n \"start_date\": \"<string>\",\n \"callback_urls\": [\n \"<string>\"\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("client_id", "<api-key>")
req.Header.Add("client_secret", "<api-key>")
req.Header.Add("access_token", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.usecobalt.com/v1/tasks")
.header("client_id", "<api-key>")
.header("client_secret", "<api-key>")
.header("access_token", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"patient_mrn\": \"12345\",\n \"description\": \"Call patient about lab results\",\n \"subject\": \"<string>\",\n \"assignee_user_id\": \"<string>\",\n \"phone_call_type_id\": \"<string>\",\n \"notify_list\": [\n \"<string>\"\n ],\n \"location_id\": \"<string>\",\n \"task_type\": \"<string>\",\n \"details\": \"<string>\",\n \"assigned_to\": \"<string>\",\n \"facility_id\": \"<string>\",\n \"due_date\": \"<string>\",\n \"start_date\": \"<string>\",\n \"callback_urls\": [\n \"<string>\"\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecobalt.com/v1/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["client_id"] = '<api-key>'
request["client_secret"] = '<api-key>'
request["access_token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"patient_mrn\": \"12345\",\n \"description\": \"Call patient about lab results\",\n \"subject\": \"<string>\",\n \"assignee_user_id\": \"<string>\",\n \"phone_call_type_id\": \"<string>\",\n \"notify_list\": [\n \"<string>\"\n ],\n \"location_id\": \"<string>\",\n \"task_type\": \"<string>\",\n \"details\": \"<string>\",\n \"assigned_to\": \"<string>\",\n \"facility_id\": \"<string>\",\n \"due_date\": \"<string>\",\n \"start_date\": \"<string>\",\n \"callback_urls\": [\n \"<string>\"\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "<string>",
"task_id": "<string>",
"job_id": 123
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}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
- Example A
- Example B
- Example C
- Example D
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"
}'
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": "Patient called requesting prescription refill for lisinopril 10mg.",
"patient_mrn": "MRN-67890",
"phone_call_type_id": "rx_refill",
"notify_list": ["user_001", "user_002"]
}'
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": "Patient reports side effects from new medication; please review.",
"patient_mrn": "MRN-24680",
"task_type": "Prescribe",
"details": "Medication",
"assigned_to": "4840",
"facility_id": "5954",
"due_date": "2026-11-25"
}'
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 '{
"patient_mrn": "MRN-13579",
"subject": "Add pharmacy",
"assigned_to": "152925",
"description": "Confirm preferred pharmacy on file.",
"due_date": "2026-11-25",
"start_date": "2026-11-18",
"priority": "Normal"
}'
Example Response
{
"success": true,
"message": "Task processing. A webhook event will be sent upon completion.",
"task_id": "abc123def456789012345678",
"job_id": 12345
}
- 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 a400 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
Body
Medical Record Number of the patient the task is about.
"12345"
Task description / body text. For ModMed EMA this is the task note. For eClinicalWorks this is the action Notes.
"Call patient about lab results"
Task subject / title. For eClinicalWorks this is the action Subject.
EMR user ID to assign the task to.
Phone call type ID for the task.
Recipients to notify. For Nextech, communication group IDs (an ehr_id from GET /v1/staff); for ModMed Gastro, recipient tasking GUIDs.
EMR location ID the task belongs to. Validated against the account’s locations.
Task type. For ModMed Gastro, a practice-specific label (defaults to "General"). For ModMed EMA, the task Type (e.g. "Prescribe", "Communication"), validated against the account. For eClinicalWorks, the action Type label (optional).
ModMed EMA "Details" value (e.g. "Medication", "Results"), validated against the account.
Staff id to assign the task to. For ModMed EMA, a staff id (an ehr_id from GET /v1/staff) or staff-group id (from staff_groups on GET /v1/settings). For eClinicalWorks, the staff EHR id the action is assigned to (an ehr_id from GET /v1/staff).
Facility id the task is filed under. Optional; defaults to the account facility when the account has a single facility. Supported for ModMed EMA and eClinicalWorks.
Task due date (ISO 8601, e.g. "2026-11-25"). Optional. Supported for ModMed EMA and eClinicalWorks.
eClinicalWorks action start date (ISO 8601, e.g. "2026-11-25"). Optional; defaults to the creation date.
eClinicalWorks action priority. Optional; defaults to "Normal".
Low, Normal, High URLs to receive the completion webhook for this task, in addition to the account webhook.