Create a task
curl --request POST \
--url https://api.maxcare.ai/v1/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Organization-Id: <x-organization-id>' \
--data '
{
"notes": "Review missing plan for Impression #3: Irritant Contact Dermatitis",
"noteId": "3cc73cb6-9c59-403c-a910-8af6c5693b25",
"patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631",
"providerId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"assigneeIds": [
"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"
],
"assigneeGroupIds": [
"4412"
],
"type": "OBTAIN",
"details": "INSURANCE",
"priority": "NORMAL",
"dueDate": "2026-11-13"
}
'import requests
url = "https://api.maxcare.ai/v1/tasks"
payload = {
"notes": "Review missing plan for Impression #3: Irritant Contact Dermatitis",
"noteId": "3cc73cb6-9c59-403c-a910-8af6c5693b25",
"patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631",
"providerId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"assigneeIds": ["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"],
"assigneeGroupIds": ["4412"],
"type": "OBTAIN",
"details": "INSURANCE",
"priority": "NORMAL",
"dueDate": "2026-11-13"
}
headers = {
"X-Organization-Id": "<x-organization-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Organization-Id': '<x-organization-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
notes: 'Review missing plan for Impression #3: Irritant Contact Dermatitis',
noteId: '3cc73cb6-9c59-403c-a910-8af6c5693b25',
patientId: '8de03039-3a9e-417a-b2b3-a8b8df183631',
providerId: 'd4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a',
assigneeIds: ['d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a'],
assigneeGroupIds: ['4412'],
type: 'OBTAIN',
details: 'INSURANCE',
priority: 'NORMAL',
dueDate: '2026-11-13'
})
};
fetch('https://api.maxcare.ai/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.maxcare.ai/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([
'notes' => 'Review missing plan for Impression #3: Irritant Contact Dermatitis',
'noteId' => '3cc73cb6-9c59-403c-a910-8af6c5693b25',
'patientId' => '8de03039-3a9e-417a-b2b3-a8b8df183631',
'providerId' => 'd4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a',
'assigneeIds' => [
'd4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a'
],
'assigneeGroupIds' => [
'4412'
],
'type' => 'OBTAIN',
'details' => 'INSURANCE',
'priority' => 'NORMAL',
'dueDate' => '2026-11-13'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Organization-Id: <x-organization-id>"
],
]);
$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.maxcare.ai/v1/tasks"
payload := strings.NewReader("{\n \"notes\": \"Review missing plan for Impression #3: Irritant Contact Dermatitis\",\n \"noteId\": \"3cc73cb6-9c59-403c-a910-8af6c5693b25\",\n \"patientId\": \"8de03039-3a9e-417a-b2b3-a8b8df183631\",\n \"providerId\": \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\",\n \"assigneeIds\": [\n \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\"\n ],\n \"assigneeGroupIds\": [\n \"4412\"\n ],\n \"type\": \"OBTAIN\",\n \"details\": \"INSURANCE\",\n \"priority\": \"NORMAL\",\n \"dueDate\": \"2026-11-13\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Organization-Id", "<x-organization-id>")
req.Header.Add("Authorization", "Bearer <token>")
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.maxcare.ai/v1/tasks")
.header("X-Organization-Id", "<x-organization-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"notes\": \"Review missing plan for Impression #3: Irritant Contact Dermatitis\",\n \"noteId\": \"3cc73cb6-9c59-403c-a910-8af6c5693b25\",\n \"patientId\": \"8de03039-3a9e-417a-b2b3-a8b8df183631\",\n \"providerId\": \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\",\n \"assigneeIds\": [\n \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\"\n ],\n \"assigneeGroupIds\": [\n \"4412\"\n ],\n \"type\": \"OBTAIN\",\n \"details\": \"INSURANCE\",\n \"priority\": \"NORMAL\",\n \"dueDate\": \"2026-11-13\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.maxcare.ai/v1/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"notes\": \"Review missing plan for Impression #3: Irritant Contact Dermatitis\",\n \"noteId\": \"3cc73cb6-9c59-403c-a910-8af6c5693b25\",\n \"patientId\": \"8de03039-3a9e-417a-b2b3-a8b8df183631\",\n \"providerId\": \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\",\n \"assigneeIds\": [\n \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\"\n ],\n \"assigneeGroupIds\": [\n \"4412\"\n ],\n \"type\": \"OBTAIN\",\n \"details\": \"INSURANCE\",\n \"priority\": \"NORMAL\",\n \"dueDate\": \"2026-11-13\"\n}"
response = http.request(request)
puts response.read_body{
"code": "success",
"data": {
"id": "a1b2c3d4-5678-4abc-9def-0123456789ab",
"status": "not_started",
"syncStatus": "synced",
"notes": "Review missing plan for Impression #3",
"dueDate": "2026-11-13",
"source": "manual",
"ehrType": "modmed",
"assignedProviders": [
{
"id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"firstName": "James",
"lastName": "Wilson",
"displayFirstName": "Dr. James",
"displayLastName": "Wilson, MD",
"username": "jwilson",
"roles": [
"Physician"
],
"individualNpi": "1234567890",
"canFinalize": true,
"canCosign": false
}
],
"createdAt": "2026-03-20 18:35:10.209452+00",
"ehrCreatedAt": "2026-01-04 09:12:44.000000+00",
"updatedAt": "2026-03-23 03:15:47.285+00",
"noteId": "3cc73cb6-9c59-403c-a910-8af6c5693b25",
"patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631"
}
}{
"code": "bad_request",
"message": "'id' must be a valid UUID",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unauthorized",
"message": "Invalid or missing API key",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "forbidden",
"message": "Insufficient scope",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "not_found",
"message": "Resource not found",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "conflict",
"message": "Cannot edit a signed note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unexpected_integration_error",
"message": "EHR sync failed",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "server_unresponsive",
"message": "EHR integration is not available for this note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}Tasks
Create a task
Creates a new task and pushes it to the EHR synchronously. Returns the task with syncStatus ‘synced’ on success, or 502 if the EHR push fails. Anchor it with exactly one of noteId (requires providerId and at least one assigneeIds entry) or patientId — a task on the patient’s chart with no note, for a chart that has none yet. A patient task may omit providerId (the practice’s system EHR user creates it), may be assigned to staff groups (assigneeGroupIds from GET /tasks/assignee-groups), and may set the EHR’s own type/details (e.g. OBTAIN/INSURANCE) and priority. Patient tasks need patientAnchor in GET /tasks/capabilities; elsewhere they get 400 capability_unsupported. Send an Idempotency-Key to make a retry safe (24 hours per app+organization; a reused key with a different body is refused with 409). A 409 ehr_write_uncertain means the task may already be in the EHR: that key keeps answering 409 for 24 hours, and a new key would create a second task, so check the patient’s tasks in the EHR before sending another.
POST
/
tasks
Create a task
curl --request POST \
--url https://api.maxcare.ai/v1/tasks \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Organization-Id: <x-organization-id>' \
--data '
{
"notes": "Review missing plan for Impression #3: Irritant Contact Dermatitis",
"noteId": "3cc73cb6-9c59-403c-a910-8af6c5693b25",
"patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631",
"providerId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"assigneeIds": [
"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"
],
"assigneeGroupIds": [
"4412"
],
"type": "OBTAIN",
"details": "INSURANCE",
"priority": "NORMAL",
"dueDate": "2026-11-13"
}
'import requests
url = "https://api.maxcare.ai/v1/tasks"
payload = {
"notes": "Review missing plan for Impression #3: Irritant Contact Dermatitis",
"noteId": "3cc73cb6-9c59-403c-a910-8af6c5693b25",
"patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631",
"providerId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"assigneeIds": ["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"],
"assigneeGroupIds": ["4412"],
"type": "OBTAIN",
"details": "INSURANCE",
"priority": "NORMAL",
"dueDate": "2026-11-13"
}
headers = {
"X-Organization-Id": "<x-organization-id>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'X-Organization-Id': '<x-organization-id>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
notes: 'Review missing plan for Impression #3: Irritant Contact Dermatitis',
noteId: '3cc73cb6-9c59-403c-a910-8af6c5693b25',
patientId: '8de03039-3a9e-417a-b2b3-a8b8df183631',
providerId: 'd4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a',
assigneeIds: ['d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a'],
assigneeGroupIds: ['4412'],
type: 'OBTAIN',
details: 'INSURANCE',
priority: 'NORMAL',
dueDate: '2026-11-13'
})
};
fetch('https://api.maxcare.ai/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.maxcare.ai/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([
'notes' => 'Review missing plan for Impression #3: Irritant Contact Dermatitis',
'noteId' => '3cc73cb6-9c59-403c-a910-8af6c5693b25',
'patientId' => '8de03039-3a9e-417a-b2b3-a8b8df183631',
'providerId' => 'd4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a',
'assigneeIds' => [
'd4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a'
],
'assigneeGroupIds' => [
'4412'
],
'type' => 'OBTAIN',
'details' => 'INSURANCE',
'priority' => 'NORMAL',
'dueDate' => '2026-11-13'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Organization-Id: <x-organization-id>"
],
]);
$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.maxcare.ai/v1/tasks"
payload := strings.NewReader("{\n \"notes\": \"Review missing plan for Impression #3: Irritant Contact Dermatitis\",\n \"noteId\": \"3cc73cb6-9c59-403c-a910-8af6c5693b25\",\n \"patientId\": \"8de03039-3a9e-417a-b2b3-a8b8df183631\",\n \"providerId\": \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\",\n \"assigneeIds\": [\n \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\"\n ],\n \"assigneeGroupIds\": [\n \"4412\"\n ],\n \"type\": \"OBTAIN\",\n \"details\": \"INSURANCE\",\n \"priority\": \"NORMAL\",\n \"dueDate\": \"2026-11-13\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Organization-Id", "<x-organization-id>")
req.Header.Add("Authorization", "Bearer <token>")
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.maxcare.ai/v1/tasks")
.header("X-Organization-Id", "<x-organization-id>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"notes\": \"Review missing plan for Impression #3: Irritant Contact Dermatitis\",\n \"noteId\": \"3cc73cb6-9c59-403c-a910-8af6c5693b25\",\n \"patientId\": \"8de03039-3a9e-417a-b2b3-a8b8df183631\",\n \"providerId\": \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\",\n \"assigneeIds\": [\n \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\"\n ],\n \"assigneeGroupIds\": [\n \"4412\"\n ],\n \"type\": \"OBTAIN\",\n \"details\": \"INSURANCE\",\n \"priority\": \"NORMAL\",\n \"dueDate\": \"2026-11-13\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.maxcare.ai/v1/tasks")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"notes\": \"Review missing plan for Impression #3: Irritant Contact Dermatitis\",\n \"noteId\": \"3cc73cb6-9c59-403c-a910-8af6c5693b25\",\n \"patientId\": \"8de03039-3a9e-417a-b2b3-a8b8df183631\",\n \"providerId\": \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\",\n \"assigneeIds\": [\n \"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a\"\n ],\n \"assigneeGroupIds\": [\n \"4412\"\n ],\n \"type\": \"OBTAIN\",\n \"details\": \"INSURANCE\",\n \"priority\": \"NORMAL\",\n \"dueDate\": \"2026-11-13\"\n}"
response = http.request(request)
puts response.read_body{
"code": "success",
"data": {
"id": "a1b2c3d4-5678-4abc-9def-0123456789ab",
"status": "not_started",
"syncStatus": "synced",
"notes": "Review missing plan for Impression #3",
"dueDate": "2026-11-13",
"source": "manual",
"ehrType": "modmed",
"assignedProviders": [
{
"id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"firstName": "James",
"lastName": "Wilson",
"displayFirstName": "Dr. James",
"displayLastName": "Wilson, MD",
"username": "jwilson",
"roles": [
"Physician"
],
"individualNpi": "1234567890",
"canFinalize": true,
"canCosign": false
}
],
"createdAt": "2026-03-20 18:35:10.209452+00",
"ehrCreatedAt": "2026-01-04 09:12:44.000000+00",
"updatedAt": "2026-03-23 03:15:47.285+00",
"noteId": "3cc73cb6-9c59-403c-a910-8af6c5693b25",
"patientId": "8de03039-3a9e-417a-b2b3-a8b8df183631"
}
}{
"code": "bad_request",
"message": "'id' must be a valid UUID",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unauthorized",
"message": "Invalid or missing API key",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "forbidden",
"message": "Insufficient scope",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "not_found",
"message": "Resource not found",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "conflict",
"message": "Cannot edit a signed note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "unexpected_integration_error",
"message": "EHR sync failed",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}{
"code": "server_unresponsive",
"message": "EHR integration is not available for this note",
"trace_id": "550e8400-e29b-41d4-a716-446655440000"
}Authorizations
Marketplace API key
Headers
Client-generated key protecting retries for 24 hours
Target clinic organization ID
Body
application/json
Task description / notes
Example:
"Review missing plan for Impression #3: Irritant Contact Dermatitis"
Note (visit) to attach the task to. Send exactly one of noteId or patientId.
Example:
"3cc73cb6-9c59-403c-a910-8af6c5693b25"
Patient whose chart the task goes on, with no visit — for a chart that has no note yet (a new referral). Send exactly one of noteId or patientId. Patient tasks are supported where GET /tasks/capabilities reports patientAnchor; elsewhere they are refused with 400 capability_unsupported.
Example:
"8de03039-3a9e-417a-b2b3-a8b8df183631"
Provider whose EHR login creates the task. Required with noteId. With patientId it is optional: omitted, the task is created by the practice's system EHR user.
Example:
"d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"
Provider IDs to assign the task to. A task needs at least one assignee or assignee group; with noteId, at least one provider is required.
Example:
["d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"]
EHR staff-group ids from GET /tasks/assignee-groups (e.g. the practice's Billing group). Patient tasks only.
Example:
["4412"]
EHR task type, using the EHR's own enum name (ModMed: REVIEW, OBTAIN, COMMUNICATION, …). Omitted: REVIEW. Patient tasks only.
Example:
"OBTAIN"
EHR task details label (ModMed: INSURANCE, …). Omitted: Normal. Patient tasks only.
Example:
"INSURANCE"
Omitted: NORMAL. Patient tasks only.
Available options:
NORMAL, HIGH Example:
"NORMAL"
Due date (YYYY-MM-DD), today or later. Patient tasks only, on EHRs whose GET /tasks/capabilities reports dueDate; elsewhere 400 capability_unsupported.
Example:
"2026-11-13"