On this page In addition to the standard API endpoints for creating, reading, and updating resources, FHIR offers a variety of RPC-like [Operation APIs](https://www.hl7.org/fhir/operations.html) to expose arbitrary functionality as a FHIR API. Each API endpoint is defined by an [`OperationDefinition`](http://hl7.org/fhir/R4/operationdefinition.html) resource, which provides information about how to call the API and what to expect in response. ## Operation Definition [​](/content/docs/api/fhir/operations#operation-definition "Direct link to Operation Definition"/index.html) For example, consider the [`ValueSet/$validate-code` operation](https://www.hl7.org/fhir/R4/valueset-operation-validate-code.html), which is summarized below: OperationDefinition JSON ```js { "resourceType": "OperationDefinition", "url": "http://hl7.org/fhir/OperationDefinition/ValueSet-validate-code", "status": "active", "kind": "operation", // Endpoint configuration "code": "validate-code", "resource": ["ValueSet"], "system": false, "type": true, "instance": true, "parameter": [ // Input Parameters { "use": "in", "name": "url", "documentation": "Value set canonical URL", "min": 0, "max": "1", "type": "uri" }, { "use": "in", "name": "valueSet", "documentation": "The value set is provided directly as part of the request", "min": 0, "max": "1", "type": "ValueSet" }, { "use": "in", "name": "code", "documentation": "The code that is to be validated", "min": 0, "max": "1", "type": "code" }, { "use": "in", "name": "system", "documentation": "The system for the code that is to be validated", "min": 0, "max": "1", "type": "uri" }, { "use": "in", "name": "display", "documentation": "The display associated with the code, if provided", "min": 0, "max": "1", "type": "string" }, { "use": "in", "name": "coding", "documentation": "A coding to validate", "min": 0, "max": "1", "type": "Coding" }, { "use": "in", "name": "codeableConcept", "documentation": "A full codeableConcept to validate", "min": 0, "max": "1", "type": "CodeableConcept" }, // Output Parameters { "use": "out", "name": "result", "documentation": "True if the concept details supplied are valid", "min": 1, "max": "1", "type": "boolean" }, { "use": "out", "name": "message", "documentation": "Error details, if result = false; otherwise may contain hints and warnings", "min": 0, "max": "1", "type": "string" }, { "use": "out", "name": "display", "documentation": "A valid display for the concept if the system wishes to display this to a user", "min": 0, "max": "1", "type": "string" } ] } ``` This definition supplies the information needed to correctly call the operation API endpoint: - All operation requests can be made using the `POST` HTTP method - The `validate-code` operation is available as type- and instance-level endpoints for `ValueSet` resources, i.e. - `[baseUrl]/ValueSet/$validate-code` - `[baseUrl]/ValueSet/[id]/$validate-code` - Input parameters are passed via a [`Parameters`](/content/docs/api/fhir/resources/parameters/index.html) resource in the request body ## Invoking an Operation [​](/content/docs/api/fhir/operations#invoking-an-operation "Direct link to Invoking an Operation"/index.html) Given the information from the `OperationDefinition`, we can construct a request to the operation API endpoint. For each `in` parameter, corresponding entries may appear in the request `Parameters.parameter` array. Value types must match the `OperationDefinition`. **Request**: - TypeScript - cURL ```ts const result = await medplum.post(medplum.fhirUrl('ValueSet', '$validate-code').toString(), { resourceType: 'Parameters', parameter: [ { name: 'url', valueUri: 'http://hl7.org/fhir/ValueSet/condition-severity' }, { name: 'coding', valueCoding: { system: 'http://snomed.info/sct', code: '255604002' } }, ], }); ``` ```bash curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \ -X POST \ -H "Content-Type: application/fhir+json" \ -H "Authorization: Bearer $MY_ACCESS_TOKEN" \ -d '{"resourceType":"Parameters","parameter":[{"name":"url","valueUri":"http://hl7.org/fhir/ValueSet/condition-severity"},{"name":"coding","valueCoding":{"system":"http://snomed.info/sct","code":"255604002"}}]}' ``` **Response**: (200 OK) ```js { "resourceType": "Parameters", "parameter": [ { "name": "result", "valueBoolean": true }, { "name": "display", "valueString": "Mild (qualifier value)" } ] } ``` ### Via GET Request [​](/content/docs/api/fhir/operations#via-get-request "Direct link to Via GET Request"/index.html) In some cases, it may be simpler to invoke an operation with a GET request and encode the input parameters in the query string of the request URL. For example, the following operation requests are equivalent: ```bash curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \ -X POST \ -H "Content-Type: application/fhir+json" \ -H "Authorization: Bearer $MY_ACCESS_TOKEN" \ -d '{"resourceType":"Parameters","parameter":[{"name":"url","valueUri":"http://hl7.org/fhir/ValueSet/condition-severity"},{"name":"coding","valueCoding":{"system":"http://snomed.info/sct","code":"255604002"}}]}' curl 'https://api.medplum.com/fhir/R4/ValueSet/$validate-code' \ --get \ -H "Authorization: Bearer $MY_ACCESS_TOKEN" \ -d 'url=http://hl7.org/fhir/ValueSet/condition-severity' \ -d 'system=http://snomed.info/sct' \ -d 'code=255604002' ``` This is possible when the request is idempotent and contains only simple input parameter types, i.e. - The `OperationDefinition` must not contain `"affectsState": true` - The request may only contain `in` parameters with a simple `type` (one starting with a lower-case letter, like `string` or `positiveInt` \- but not `Coding`) ## Reading the Response [​](/content/docs/api/fhir/operations#reading-the-response "Direct link to Reading the Response"/index.html) For each `out` parameter in the response, the typed value(s) are recorded in the `Parameters.parameter` array. Multiple values for a given output parameter will appear as multiple entries in the array, **not** a nested array in the `value[x]` field. ### Error Responses [​](/content/docs/api/fhir/operations#error-responses "Direct link to Error Responses"/index.html) In case of an error, the server will return an HTTP status code in the 4xx-5xx range. The response body will contain an `OperationOutcome` resource with details about the error. For example, if the specified `ValueSet` could not be found by URL: ```js { "resourceType": "OperationOutcome", "issue": [ { "severity": "error", "code": "invalid", "details": { "text": "ValueSet http://example.com/ValueSet/missing not found" } } ] } ``` ## Operation Documentation [​](/content/docs/api/fhir/operations#operation-documentation "Direct link to Operation Documentation"/index.html) Details about the FHIR Operations supported by Medplum server are organized below by category. For information about other available operations, see the [complete list](https://www.hl7.org/fhir/R4/operationslist.html) from the FHIR specification. ### Terminology Operations [​](/content/docs/api/fhir/operations#terminology-operations "Direct link to Terminology Operations"/index.html) Operations for managing CodeSystem, ConceptMap, and ValueSet resources. **CodeSystem:** - [CodeSystem/$import](/content/docs/api/fhir/operations/codesystem-import/index.html) \- Import codes into a CodeSystem - [CodeSystem/$lookup](/content/docs/api/fhir/operations/codesystem-lookup/index.html) \- Look up code details - [CodeSystem/$subsumes](/content/docs/api/fhir/operations/codesystem-subsumes/index.html) \- Test subsumption relationship - [CodeSystem/$validate-code](/content/docs/api/fhir/operations/codesystem-validate-code/index.html) \- Validate a code in a CodeSystem **ConceptMap:** - [ConceptMap/$import](/content/docs/api/fhir/operations/conceptmap-import/index.html) \- Import mappings into a ConceptMap - [ConceptMap/$translate](/content/docs/api/fhir/operations/conceptmap-translate/index.html) \- Translate a code using a ConceptMap **ValueSet:** - [ValueSet/$expand](/content/docs/api/fhir/operations/valueset-expand/index.html) \- Expand a ValueSet - [ValueSet/$validate-code](/content/docs/api/fhir/operations/valueset-validate-code/index.html) \- Validate a code against a ValueSet ### Patient Operations [​](/content/docs/api/fhir/operations#patient-operations "Direct link to Patient Operations"/index.html) Operations specific to Patient resources. - [Patient/$everything](/content/docs/api/fhir/operations/patient-everything/index.html) \- Retrieve all patient data - [Patient/$summary](/content/docs/api/fhir/operations/patient-summary/index.html) \- Generate International Patient Summary (IPS) ### Bot Operations [​](/content/docs/api/fhir/operations#bot-operations "Direct link to Bot Operations"/index.html) Deploy, execute, and extend Medplum Bots. - [Bot/$deploy](/content/docs/api/fhir/operations/bot-deploy/index.html) \- Deploy bot code - [Bot/$execute](/content/docs/api/fhir/operations/bot-execute/index.html) \- Execute a bot - [Custom Bot Operations](/content/docs/api/fhir/operations/custom-operations/index.html) \- Create custom FHIR operations with Bots ### Resource Validation & Transformation [​](/content/docs/api/fhir/operations#resource-validation--transformation "Direct link to Resource Validation & Transformation"/index.html) Validate resources and transform data structures. - [$graph](/content/docs/api/fhir/operations/resource-graph/index.html) \- Fetch related resources via GraphDefinition - [GraphQL](/content/docs/api/fhir/operations/graphql/index.html) \- Query resources using GraphQL - [Questionnaire/$extract](/content/docs/api/fhir/operations/extract/index.html) \- Extract data from QuestionnaireResponse - [Resource/$validate](/content/docs/api/fhir/operations/validate-a-resource/index.html) \- Validate a resource against profiles - [StructureDefinition/$expand-profile](/content/docs/api/fhir/operations/structuredefinition-expand-profile/index.html) \- Expand a StructureDefinition with nested profiles ### Data Export & Import [​](/content/docs/api/fhir/operations#data-export--import "Direct link to Data Export & Import"/index.html) Bulk data operations and format conversions. - [$csv](/content/docs/api/fhir/operations/csv/index.html) \- Export resources as CSV - [Bulk Data Export](/content/docs/api/fhir/operations/bulk-fhir/index.html) \- FHIR Bulk Data Access - [CCDA Export](/content/docs/api/fhir/operations/ccda-export/index.html) \- Export data as C-CDA documents - [Claim/$export](/content/docs/api/fhir/operations/claim-export/index.html) \- Export claims as CMS-1500 PDFs ### Clinical Decision Support [​](/content/docs/api/fhir/operations#clinical-decision-support "Direct link to Clinical Decision Support"/index.html) Operations for measures, clinical plans, charges, and AI assistance. - [AI Assistant](/content/docs/api/fhir/operations/ai/index.html) \- AI-powered clinical assistance - [ChargeItemDefinition/$apply](/content/docs/api/fhir/operations/chargeitemdefinition-apply/index.html) \- Apply pricing rules to ChargeItem - [Measure/$evaluate-measure](/content/docs/api/fhir/operations/evaluate-measure/index.html) \- Evaluate a clinical quality measure - [PlanDefinition/$apply](/content/docs/api/fhir/operations/plandefinition-apply/index.html) \- Apply a PlanDefinition to generate resources ### Project & System Administration [​](/content/docs/api/fhir/operations#project--system-administration "Direct link to Project & System Administration"/index.html) Project management and system operations. - [AsyncJob/$cancel](/content/docs/api/fhir/operations/asyncjob-cancel/index.html) \- Cancel an asynchronous job - [Project/$clone](/content/docs/api/fhir/operations/project-clone/index.html) \- Clone a Medplum project - [Project/$init](/content/docs/api/fhir/operations/project-init/index.html) \- Initialize a new project - [Project/$rate-limits](/content/docs/api/fhir/operations/project-rate-limits/index.html) \- View FHIR interaction quota usage - [$expunge](/content/docs/api/fhir/operations/expunge/index.html) \- Permanently delete resources - [$resend](/content/docs/api/fhir/operations/resend/index.html) \- Resend a subscription notification - [$set-accounts](/content/docs/api/fhir/operations/set-accounts/index.html) \- Set resource account references ### Authentication & Security [​](/content/docs/api/fhir/operations#authentication--security "Direct link to Authentication & Security"/index.html) Client application, credential, and user management operations. - [ClientApplication/$rotate-secret](/content/docs/api/fhir/operations/rotate-client-secret/index.html) \- Rotate client secrets - [ClientApplication/$smart-launch](/content/docs/api/fhir/operations/clientapplication-smart-launch/index.html) \- SMART on FHIR app launch - [User/$rescope](/content/docs/api/fhir/operations/user-rescope/index.html) \- Move a user between server and project scope - [User/$update-email](/content/docs/api/fhir/operations/user-update-email/index.html) \- Update user email address - [Operation Definition](/content/docs/api/fhir/operations#operation-definition/index.html) - [Invoking an Operation](/content/docs/api/fhir/operations#invoking-an-operation/index.html) - [Via GET Request](/content/docs/api/fhir/operations#via-get-request/index.html) - [Reading the Response](/content/docs/api/fhir/operations#reading-the-response/index.html) - [Error Responses](/content/docs/api/fhir/operations#error-responses/index.html) - [Operation Documentation](/content/docs/api/fhir/operations#operation-documentation/index.html) - [Terminology Operations](/content/docs/api/fhir/operations#terminology-operations/index.html) - [Patient Operations](/content/docs/api/fhir/operations#patient-operations/index.html) - [Bot Operations](/content/docs/api/fhir/operations#bot-operations/index.html) - [Resource Validation & Transformation](/content/docs/api/fhir/operations#resource-validation--transformation/index.html) - [Data Export & Import](/content/docs/api/fhir/operations#data-export--import/index.html) - [Clinical Decision Support](/content/docs/api/fhir/operations#clinical-decision-support/index.html) - [Project & System Administration](/content/docs/api/fhir/operations#project--system-administration/index.html) - [Authentication & Security](/content/docs/api/fhir/operations#authentication--security/index.html)