Composition

Description

Creates a Composition resource to submit structured visit note content for a patient encounter through the API. This resource acts as the clinical document container for the visit note, organizing different clinical sections such as chief complaint, history of present illness, family history, physical exam, vitals, evaluation, procedures, plan of care, and patient instructions.

The Composition must reference an existing patient and encounter, and the encounter must be an active encounter used for visit documentation. The document type for this implementation is Progress Note using the appropriate LOINC code. The Composition may include one or more authors, which can be Practitioners or an Organization when the specific provider is not known.

The visit note is structured using sections, where each section represents a specific clinical area. Each section is identified using a LOINC-coded section type and may contain narrative text.

Mapping between the incoming LOINC section codes and the EHR visit note layout is managed through a system configuration. Administrators can configure how each section appears in the visit note interface using the following setup within the EHR:

Setup → Visit Note → Template Configuration for AI Powered Visit Note Documentation

This configuration links the LOINC-coded sections received through the Composition resource to the appropriate visit note template sections displayed in the EHR's visit note left panel.

For this implementation, the Composition resource is treated as a final document submission. Vendors must send only finalized information, and the system will treat incoming data as final. Requests containing statuses other than final may be rejected. External systems cannot delete visit note data, and the entered-in-error status is not supported.

To support integrations with multiple vendors (such as AI scribes or documentation systems), the system follows an append-only model. New information submitted through the API is appended to the visit note sections rather than replacing existing content. This ensures that multiple vendors can contribute documentation to the same encounter without overwriting existing information. Any rearrangement or modification of the visit note content is handled by the user directly within the EHR.

The Composition resource is primarily responsible for defining the structure and narrative of the visit note, while detailed clinical data (such as vitals, procedures, medications, or diagnoses) should be created using their respective FHIR resource write APIs and referenced where appropriate within the visit note sections.

Interaction:

POST Request

HTTP Method: POST

POST {{Url}}/Composition

cURL

curl -X POST "{{url}}/mps/fhir/R4/V1/Composition/" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/fhir+json" \
  --data-raw '{
    "resourceType": "Composition",
    "id": "composition-10012",
    "status": "final",
    "type": {
      "coding": [
        {
          "system": "http://loinc.org",
          "code": "11506-3",
          "display": "Progress note"
        }
      ]
    },
    "subject": {
      "reference": "Patient/Patient-265",
      "display": "John Smith"
    },
    "encounter": {
      "reference": "Encounter/Encounter-805"
    },
    "date": "2025-06-06T10:00:00Z",
    "author": [
      {
        "reference": "Practitioner/Practitioner-1",
        "display": "Dr. Linda Jones"
      }
    ],
    "title": "Visit Note",
    "custodian": {
      "reference": "Organization/Organization-1",
      "display": "General Hospital"
    },
    "section": [
      {
        "title": "Chief Complaints",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "10154-3",
              "display": "Chief complaint Narrative"
            }
          ]
        },
        "text": {
          "status": "generated",
          "div": "<div><p>Patient reports intermittent che...</p></div>"
        }
      },
      {
        "title": "History of Present Illness",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "10164-2",
              "display": "History of present illness Narrative"
            }
          ]
        },
        "text": {
          "status": "generated",
          "div": "<div><p>Siddharth is complaining Chest p...</p></div>"
        }
      },
      {
        "title": "Evaluation",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "51848-0",
              "display": "Evaluation note"
            }
          ]
        },
        "text": {
          "status": "generated",
          "div": "<div><p>Patient evaluated for possible m...</p></div>"
        }
      },
      {
        "title": "Plan of Care",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "18776-5",
              "display": "Plan of care note"
            }
          ]
        },
        "text": {
          "status": "generated",
          "div": "<div><p>Continue Lisinopril 10 mg daily....</p></div>"
        }
      },
      {
        "title": "Instructions",
        "code": {
          "coding": [
            {
              "system": "http://loinc.org",
              "code": "69730-0",
              "display": "Instructions"
            }
          ]
        },
        "text": {
          "status": "generated",
          "div": "<div><p>Avoid strenuous activity for the...</p></div>"
        }
      }
    ]
  }'

Composition Resource Content

Element	Child Element	Description	R / O / C	Cardinality	Condition / Notes
`resourceType`	—	Identifies the FHIR resource type.	Required	1..1	Must always be Composition.
`id`	—	Unique identifier for the composition resource.	Optional	0..1	Generated by FHIR server.
`status`	—	Status of the document.	Required	1..1	Value: final.
`type`	—	Type of clinical document.	Required	1..1	Defines the document category.
`type`	`coding.system`	Coding system for document type.	Required	1..1	http://loinc.org.
`type`	`coding.code`	LOINC code representing document type.	Required	1..1	Example: 11506-3.
`type`	`coding.display`	Description of the document type.	Required	1..1	Example: Progress note.
`subject`	—	Patient associated with the document.	Optional	1..1	Reference to patient resource.
`subject`	`reference`	Patient reference identifier.	Optional	1..1	Example: Patient/Patient-265.
`subject`	`display`	Patient display name.	Optional	0..1	Example: John Smith.
`encounter`	—	Encounter associated with the visit note.	Required	1..1	Reference to encounter resource.
`encounter`	`reference`	Encounter resource identifier.	Required	1..1	Example: Encounter/Encounter-805.
`date`	—	Date/time when the document was created.	Required	1..1	ISO datetime format.
`author`	—	Practitioner responsible for the document.	Optional	1..*	Reference to practitioner resource.
`author`	`reference`	Practitioner reference identifier.	Optional	1..1	Example: Practitioner/Practitioner-1.
`author`	`display`	Practitioner display name.	Optional	0..1	Example: Dr. Linda Jones.
`title`	—	Title of the document.	Required	1..1	Example: Visit Note.
`custodian`	—	Organization responsible for maintaining the document.	Optional	1..1	Reference to organization resource.
`custodian`	`reference`	Organization reference identifier.	Optional	1..1	Example: Organization/Organization-1.
`custodian`	`display`	Organization display name.	Optional	0..1	Example: General Hospital.
`section`	—	Sections included in the clinical document.	Required	1..*	Each section represents a structured note component.
`section`	`title`	Title of the document section.	Required	1..1	Example: Chief Complaints, History of Present Illness, Evaluation, Plan of Care, Instructions.
`section`	`code`	Code representing the section type.	Required	1..1	Uses LOINC codes for section classification.
`section.code`	`coding.system`	Code system for section.	Required	1..1	http://loinc.org.
`section.code`	`coding.code`	LOINC code for section.	Required	1..1	Example: 10154-3, 10164-2, 51848-0, 18776-5, 69730-0.
`section.code`	`coding.display`	Description of the section.	Required	1..1	Example: Chief complaint Narrative.
`section`	`text`	Narrative content for the section.	Required	1..1	Contains structured XHTML text.
`section.text`	`status`	Status of narrative text.	Required	1..1	Value: generated.
`section.text`	`div`	XHTML formatted content for the section.	Required	1..1	Contains the narrative note text wrapped in a <div> element.

Response Codes

Response Code	Description
200 OK	The requested resource was found and is contained within the body of the HTTP response.
201 Created	A new resource was created succesfully. It will return the resource with the EHR generate resource id.
400 Bad Request	The server could not understand the request due to invalid syntax. The body of the HTTP response will contain an OperationOutcome resource that indicates the invalid request could not be processed.
404 Not Found	The requested resource does not exist. The body of the HTTP response will contain an OperationOutcome resource that indicates the resource could not be found.
410 Gone	The requested resource has been permanently deleted from the server with no forwarding address. The body of the HTTP response will contain an OperationOutcome resource that indicates the resource could not be found.
422 Unprocessable Entity	The request was well-formed but had semantic errors.
500 Internal Server Error	The server has encountered a situation it doesn't know how to handle. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.
5xx Server Error	The server may return other error codes to indicate other error conditions. The body of the HTTP response will contain an OperationOutcome resource that indicates the nature of the error.
500001 VALIDATION_FAILED	The request failed validation.
500002 DUPLICATE_RECORD	A duplicate record was detected.
500003 INSERT_FAILED	The insert operation failed.
500004 UPDATE_FAILED	The update operation failed.
500005 DELETE_FAILED	The delete operation failed.
500006 RECORD_NOT_FOUND_FOR_UPDATE	No matching record was found to update.
500007 DATA_MAPPING_ERROR	The request could not be processed due to a data mapping error.
500008 DEPENDENCY_FAILURE	A dependent operation failed.
500009 ENCOUNTER_SIGNED_OFF	The encounter is already signed-off.
500010 ENCOUNTER_BILLED	The encounter is fully or partially billed.
500011 INSURANCE_ACTIVE_ALREADY_EXISTS	Same insurance with Active status is already exist.
500012 INSURANCE_PLAN_NOT_FOUND	Insurance Plan does not exist.
500013 CARRIER_CODE_DUPLICATED	Carrier code is duplicated.
500014 PLAN_CODE_DUPLICATED	Plan code is duplicated.
590002 VALUE_OUT_OF_RANGE	A value is out of range for the destination.
590001 ROW_NOT_FOUND	Row not found in global temporary table.
590003 NUMERIC_EXPECTED	Numeric value expected but found empty value.
590004 VITAL_ALREADY_PRESENT	Value for vital is already present and parameter to add multiple vital is off.
590006 HEIGHT_UNIT_UNSUPPORTED	Only feet, inch and cm are supported for height (when unit code not in cm, in_i, ft_i).
590007 COMPONENT_INFO_MISSING	Component information missing (LOINC code or data for component is missing).
590005 LOINC_MAPPING_NOT_FOUND	Mapping not found for LOINC code in IMS.
500015 APPOINTMENT_NOT_FOUND	Appointment not found.
500016 APPOINTMENT_ALREADY_CANCELLED	Appointment is already cancelled.
500017 APPOINTMENT_COMPLETED	Appointment is already completed.
500018 INVALID_STATUS	Invalid or missing status value.
500019 SERVICE_TYPE_NOT_RECOGNIZED	serviceType code not recognized.
500020 APPOINTMENT_TYPE_NOT_RECOGNIZED	appointmentType code not recognized.
500021 PROVIDER_NOT_FOUND	provider not found.
500022 LOCATION_NOT_FOUND	location not found.
500023 PATIENT_NOT_FOUND	Patient not found.
500024 ENCOUNTER_NOT_FOUND	Encounter not found.
500026 TYPE_REQUIRED	Type is required.
500027 INVALID_PARTICIPANT_REFERENCE	Invalid participant reference.
500028 ORGANIZATION_NOT_INSURANCE_CARRIER	The provided organization-id does not belong to an insurance carrier.
500029 INVALID_PERIOD_RANGE	Start date time cannot be greater than end date time.
500030 CPT_DESCRIPTION_REQUIRED	CPT description is required to create a new CPT entry in IMS.
500031 INVALID_DATE_RANGE	Start date cannot be greater than end date.
500032 ANESTHETIC_PERIOD_REQUIRED	Period start and end datetime is required for Anesthetic CPT.
500033 REFERENCE_NOT_FOUND	Reference not found.
500034 DENTAL_CPT_NOT_ALLOWED	The selected CPT code is classified as dental and cannot be included on this superbill. Please choose a non-dental CPT code.
500035 SUBSCRIBER_NOT_FOUND	Subscriber not found.
500036 DUPLICATE_ICD	Duplicate ICDs are not allowed.
500037 REFERENCED_ICD_MISSING	Referenced ICD is missing in patient diagnosis.
500038 SEVERITY_NOT_SUPPORTED	Severity is not supported
PATERR001 Missing chartNo	Missing required chartNo field.
PATERR003 Missing name	Missing required firstname or lastname field.
PATERR004 Invalid email	Email should be in proper format.
PATERR005 Invalid phone/fax length	Fax and Phone length must be 10 digits only.
APPT001 Missing serviceType	Missing required serviceType field.
APPT002 ServiceType not recognized	serviceType code not recognized.
APPT003 Invalid status	Invalid or missing status value.
APPT004 Invalid time range	start time must be before end time.
APPT006 AppointmentType not recognized	appointmentType code not recognized.
APPT007 Created date missing	Created date is missing.
APPT008 Invalid minimumDuration	minimumDuration must be positive.
APPT009 Created date in future	created date must not be in the future.
APPT0010 Missing patient reference	Reference for patient is missing.
APPT0011 Missing provider reference	Reference for provider is missing.
APPT0012 Missing location reference	Reference for location is missing.
APPT0014 Provider not found	provider not found.
APPT0015 Location not found	location not found.
APPT0016 Missing provider or location	Reference for either provider or location is needed.
APPT0017 Missing organization reference	Reference for organization is missing.
APPTR001 Missing appointment reference	Missing Appointment Reference.
APPTR002 Appointment not found	Appointment Not found.
APPTR003 Appointment already cancelled	Appointment is already cancelled.
APPTR004 Appointment already completed	Appointment is already completed.
OrgINS001 Organization ID required	Organization ID is required.
OrgINS002 Invalid organization type	Organization Type must be defined with ins.
OrgINS003 Name required	name must present.
OrgINS004 Carrier code duplicated	Carrier code is duplicated.
INSPLAN001 InsurancePlan ID required	InsurancePlan ID is required.
INSPLAN002 Plan code required	Plan code must present.
INSPLAN003 Period required	Period must present.
INSPLAN004 Name required	name must present.
INSPLAN005 Organization reference required	Reference must be there for an organization.
INSPLAN006 Invalid period range	end date can not be lesser then start date.
INSPLAN007 Status required	Staus must present.
INSPLAN008 Status must be active	Staus must be active.
COVERR001 Invalid coverage status	Status must be one of: active, cancelled.
COVERR002 Invalid subscriber reference	Subscriber must reference a Patient or RelatedPerson.
COVERR003 Subscriber ID required	Subscriber ID (Policy Id) is required.
COVERR004 Invalid beneficiary reference	Beneficiary must reference a Patient.
COVERR005 Invalid relationship	Relatioship is invalid.
COVERR006 Invalid payor reference	Payor must reference an organization.
COVERR007 Relationship required	Relatioship is required.
COVERR008 Insurance order required	Insurance order is required.
RELPERR001 RelatedPerson ID required	RelatedPerson ID is required.
RELPERR002 Patient reference required	Patient reference is required.
RELPERR003 Name required	Name is required.
RELPERR004 Birthdate required	Birthdate must present.
RELPERR005 Identifier required	Idnetifier is required.
GEN011 Missing Procedure Status	Missing Procedure Status.
PRO001 Invalid procedure code	Invalid or missing procedure code.
PRO003 Invalid subject reference	Invalid or missing subject reference.
PRO004 Invalid encounter reference	Invalid or missing encounter reference.
PRO005 Invalid performed date/time	Invalid or missing performed date/time.
PRO006 Invalid reasonReference	Invalid reasonReference.
CON002 Invalid severity code	Invalid severity code.
CON003 Invalid diagnosis code	Missing or invalid diagnosis code. Diagnosis code not found in EHR master data; please add to user diagnosis master.
CON003 Invalid bodySite coding	Invalid bodySite coding.
VIT001 Invalid category	Invalid category: must be 'vital-signs' from the specified coding system.
VIT002 Invalid observation code	Invalid or unsupported observation code.
VIT005 Invalid effectiveDateTime	Invalid or missing effectiveDateTime; must be a valid ISO 8601 datetime string.
VIT006 Invalid valueQuantity	Missing or invalid valueQuantity for observation.
VIT007 Invalid component details	Missing or invalid component details for observation.
VIT008 Invalid component code	Invalid component code.
VIT009 Invalid component valueQuantity	Missing or invalid component valueQuantity.
VIT011 Invalid component valueCodeableConcept	Invalid component valueCodeableConcept for measurement site.
VIT008 Vital not supported	Vital sign '{code}' is not supported by the EHR system.
VIT009 Vital value out of range	Vital sign value {value} is out of acceptable clinical range.

Product Information

IMS (14.0.SP1)