--- updatedAt: 2026-06-24T19:22:21.000Z agentTools: projectIndex: https://portal.api.modmed.com/llms.txt --- # Search Tasks by certain parameters Use [Authentication Endpoint](https://portal.api.modmed.com/reference/post_ws-oauth2-grant#/) page to get token # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "EMA Proprietary API", "contact": { "email": "ankit.srivastava@modmed.com" }, "version": "3.4.3_FINAL", "description": "The EMA Proprietary FHIR API provides programmatic access to ModMed EMA clinical and practice-management data using FHIR R4-style resources under `/fhir/v2`.\n\nThis documentation targets the **public sandbox** (`stage.ema-api.com`).\n\n**Authentication.** Two mechanisms are supported during the current migration: the **legacy OAuth2 `password` grant** (being sunset) and the **new OAuth2 `client_credentials`** flow (recommended for new integrations) — see the **Authentication** guide. Every API call also requires the `x-api-key` header." }, "servers": [ { "url": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema" } ], "tags": [ { "name": "Tasks/Recalls", "description": "EMA Tasks (code=TASK, default) and PM Recalls (code=PMRECALL). Task supports Create, Read, Update, and Search. PM Recalls are read-only through this endpoint. An unrecognized code value returns an OperationOutcome error listing the valid values (PMRECALL, TASK)." } ], "paths": { "/fhir/v2/Task": { "get": { "tags": [ "Tasks/Recalls" ], "summary": "Search Tasks by certain parameters", "parameters": [ { "name": "_count", "in": "query", "description": "Number of records to use as the page size for paginated search. The maximum page size for this Resource is 50", "required": false, "schema": { "type": "string" } }, { "name": "_lastUpdated", "in": "query", "description": "This is an Optional Date in the format _lastUpdated=gtDATE, _lastUpdated=eqDATE and _lastUpdated=leDATE in the format yyyy-mm-dd. For EMA tasks this searches the task's last-modified date; for PM Recalls it also matches against recall activity timestamps.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "authored-on", "in": "query", "description": "Search by the date the task was created (Task.authoredOn).", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "based-on", "in": "query", "description": "Search by the ServiceRequest (lab order) this task is based on. The ServiceRequest must resolve to a lab request/order belonging to the authenticated firm; if it doesn't, the search returns zero results.", "required": false, "schema": { "type": "string" } }, { "name": "code", "in": "query", "description": "Selects which task type to search: TASK (default) for general EMA tasks, or PMRECALL for PM Recalls. Does not filter within a type. Any other value returns an OperationOutcome error (400/422) listing the valid values.", "required": false, "schema": { "type": "string" } }, { "name": "encounter", "in": "query", "description": "Search by the visit (Encounter) associated with the task.", "required": false, "schema": { "type": "string" } }, { "name": "location", "in": "query", "description": "Search by the facility (Location) assigned to the task.", "required": false, "schema": { "type": "string" } }, { "name": "modified", "in": "query", "description": "Search by the task's last-modified timestamp. Distinct from _lastUpdated.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "page", "in": "query", "description": "Page to be used for paginated search", "required": false, "schema": { "type": "string" } }, { "name": "patient", "in": "query", "description": "Search by the patient (Task.for).", "required": false, "schema": { "type": "string" } }, { "name": "performer", "in": "query", "description": "Search by assignee. Accepts either a Practitioner reference (an individual assignee) or a CT-GRP|{id} CareTeam identifier (a staff-group assignee).", "required": false, "schema": { "type": "string" } }, { "name": "period", "in": "query", "description": "Search by the task's due date (Task.executionPeriod.end). This is a single due-date match, not a start/end range.", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "requester", "in": "query", "description": "Search by the staff member who created or last modified the task (Task.requester).", "required": false, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "ready | received | completed | cancelled", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/fhir+json": { "schema": { "$ref": "#/components/schemas/FHIR-JSON-RESOURCE" }, "example": { "resourceType": "Bundle", "id": "5a11e8cf-611c-4ba6-b84e-7af7ea7ae206", "meta": { "lastUpdated": "2026-08-28T17:58:37.321+00:00" }, "type": "searchset", "total": 50, "link": [ { "relation": "self", "url": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Task?code=TASK&_count=1" }, { "relation": "next", "url": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Task?code=TASK&_count=1&page=2" } ], "entry": [ { "fullUrl": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Task/TASK%7C5860", "resource": { "resourceType": "Task", "id": "TASK|5860", "status": "cancelled", "intent": "order", "priority": "routine", "code": { "coding": [ { "system": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/ValueSet/task-type", "code": "TASK", "display": "Task" } ], "text": "Task" }, "description": "ORDER: DISCUSS_AT_FOLLOW_UP", "for": { "reference": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Patient/39438", "display": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Patient/39438" }, "authoredOn": "2018-03-05T21:31:12+00:00", "requester": { "reference": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Practitioner/1178", "display": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Practitioner/1178" }, "location": { "reference": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Location/9", "display": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Location/9" }, "note": [ { "text": "three" } ], "input": [ { "type": { "coding": [ { "system": "http://modmed.com/fhir/task-careteam-type", "code": "IND", "display": "IND" } ], "text": "Performer with Role: DOCTOR" }, "valueReference": { "reference": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Practitioner/1178", "display": "https://stage.ema-api.com/ema-dev/firm/apiportal/ema/fhir/v2/Practitioner/1178" } } ] } } ] } }, "application/fhir+xml": { "schema": { "$ref": "#/components/schemas/FHIR-XML-RESOURCE" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "security": [ { "BearerAuth": [], "ApiKeyAuth": [] } ], "components": { "schemas": { "FHIR-JSON-RESOURCE": { "type": "object", "description": "A FHIR resource" }, "FHIR-XML-RESOURCE": { "type": "object", "description": "A FHIR resource" } }, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "OAuth2 access token (JWT). Obtain it via the legacy `password` grant or the new `client_credentials` flow (see the **Authentication** guide), then send as `Authorization: Bearer `.", "x-default": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJhN2NiZmYwZWUxYjk0ODkwOWMxZmQzYzk3ODhlZjc1NCIsImlzcyI6Im1vZG1lZCIsInN1YiI6ImZoaXJfUWZMbG8iLCJ1cmxQcmVmaXgiOiJhcGlwb3J0YWwiLCJ0b2tlblR5cGUiOiJhY2Nlc3MiLCJ2ZW5kb3IiOiJmaGlyX1FmTGxvQGFwaXBvcnRhbCIsInBvbCI6ImNoYW5nZW1lIn0.f0VcA3R56IuAvdbPhInqUbhmEwk-tiOIeELVpTZCUZ8" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Shared **sandbox** API key (public sandbox only). Send as the `x-api-key` header.\n\n`Zt9tXPIgz17uxEU6gkZPWa3ZAFhZOqm04oEDHC1f`", "x-default": "Zt9tXPIgz17uxEU6gkZPWa3ZAFhZOqm04oEDHC1f" } }, "responses": { "BadRequest": { "description": "BAD REQUEST - The request was bad, often due to a missing required parameter" }, "Unauthorized": { "description": "NOT AUTHORIZED - Authentication error; this token is not allowed access to the API" }, "Forbidden": { "description": "FORBIDDEN" }, "NotFound": { "description": "NOT FOUND" }, "UnprocessableEntity": { "description": "UNPROCESSABLE ENTITY - Request could not be processed; typically a validation error" }, "TooManyRequests": { "description": "TOO MANY REQUESTS - Request was rate limited (1000 calls/min default); please retry" }, "ServerError": { "description": "SERVER ERROR - Internal Server Error" } } } } ```