Skip to main content
POST
Create a task
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

Example Response

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:

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

Failure

Authorizations

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

Body

application/json
patient_mrn
string
required

Medical Record Number of the patient the task is about.

Example:

"12345"

description
string

Task description / body text. For ModMed EMA this is the task note. For eClinicalWorks this is the action Notes.

Example:

"Call patient about lab results"

subject
string

Task subject / title. For eClinicalWorks this is the action Subject.

assignee_user_id
string

EMR user ID to assign the task to.

phone_call_type_id

Phone call type ID for the task.

notify_list
string[]

Recipients to notify. For Nextech, communication group IDs (an ehr_id from GET /v1/staff); for ModMed Gastro, recipient tasking GUIDs.

location_id
string

EMR location ID the task belongs to. Validated against the account’s locations.

task_type
string

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).

details
string

ModMed EMA "Details" value (e.g. "Medication", "Results"), validated against the account.

assigned_to

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

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.

due_date
string

Task due date (ISO 8601, e.g. "2026-11-25"). Optional. Supported for ModMed EMA and eClinicalWorks.

start_date
string

eClinicalWorks action start date (ISO 8601, e.g. "2026-11-25"). Optional; defaults to the creation date.

priority
enum<string>

eClinicalWorks action priority. Optional; defaults to "Normal".

Available options:
Low,
Normal,
High
callback_urls
string[]

URLs to receive the completion webhook for this task, in addition to the account webhook.

Response

Task queued for processing

success
boolean
required
message
string
required
task_id
string
required
job_id
integer
required