Procedure

Description

Creates a Procedure resource to record a performed clinical procedure within the EHR. This API is used to write superbill procedures for a patient under a specific encounter. The procedure must be associated with an open encounter, and the system will reject the request if the encounter is signed off or closed.

The procedure represents a completed service performed for the patient and is primarily used for billing and clinical documentation through CPT codes. Only CPT codes are supported for procedure coding in this implementation.

Each procedure must reference the patient (subject) and the encounter where the service was performed. The performed date-time represents the start date and time of the procedure. Optionally, the procedure can include a recordedDate indicating when the procedure was documented in the system.

A procedure may also reference a Condition resource when the procedure is associated with a diagnosis included in the superbill. The procedure status defaults to completed unless explicitly provided otherwise.

Special Notes

Anesthesia CPT codes must use performedPeriod instead of a single performedDateTime. The start and end times are required so that the EHR can calculate anesthesia units based on the system configuration.
The procedure status defaults to completed unless explicitly provided otherwise.
Dental CPT codes are not supported.

Interaction:

POST Request

HTTP Method: POST

POST {{Url}}/Procedure

cURL

curl -X POST "{{url}}/mps/fhir/R4/V1/Procedure/" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "resourceType": "Procedure",
    "id": "procedure-1001",
    "meta": {
      "profile": [
        "http://hl7.org/fhir/us/core/StructureDefinition/us-core-procedure"
      ]
    },
    "status": "completed",
    "category": {
      "coding": [
        {
          "system": "http://snomed.info/sct",
          "code": "387713003",
          "display": "Surgical procedure"
        }
      ]
    },
    "code": {
      "coding": [
        {
          "system": "http://www.ama-assn.org/go/cpt",
          "version": "2023",
          "code": "20610",
          "display": "Arthrocentesis, aspiration and/or injection, major joint or bursa"
        }
      ]
    },
    "subject": {
      "reference": "Patient/Patient-265"
    },
    "encounter": {
      "reference": "Encounter/Encounter-805"
    },
    "performedDateTime": "2026-03-14T10:00:00-05:00",
    "recordedDate": "2026-03-14T10:05:00-05:00",
    "reasonReference": [
      {
        "reference": "Condition/Condition-Problem-I-1332"
      }
    ]
  }'

Procedure Resource Content

Element	Child Element	Description	R / O / C	Cardinality	Condition / Notes
`resourceType`	—	Identifies the FHIR resource type.	Required	1..1	Must always be Procedure.
`id`	—	Unique identifier for the procedure record.	Optional	0..1	Used to uniquely identify the procedure for a patient.
`status`	—	Status of the procedure.	Required	1..1	Allowed values: completed, entered-in-error. Default value: completed.
`category`	—	High-level classification of the procedure.	Optional	0..1	Used to categorize procedure type.
`category`	`coding.system`	Coding system for procedure category.	Optional	0..1	http://snomed.info/sct.
`category`	`coding.code`	SNOMED CT code representing procedure category.	Optional	0..1	Example values: 24642003, 409063005, 409073007, 387713003, 103693007, 46947000, 410606002.
`category`	`coding.display`	Description of the procedure category.	Optional	0..1	Example: Surgical procedure, Counseling, Diagnostic procedure.
`code`	—	Procedure code information.	Required	1..1	Represents the performed procedure.
`code`	`coding.system`	Coding system used for the procedure.	Required	1..1	Only CPT (http://www.ama-assn.org/go/cpt) will be considered.
`code`	`coding.version`	Version of the coding system.	Optional	0..1	Example: 2023.
`code`	`coding.code`	Procedure code value.	Required	1..1	—
`code`	`coding.display`	Description of the procedure code.	Required	1..1	—
`subject`	—	Patient on whom the procedure was performed.	Optional	1..1	Reference to a Patient resource.
`subject`	`reference`	Reference to patient.	Optional	1..1	Example: Patient/Patient-265.
`encounter`	—	Encounter associated with the procedure.	Required	1..1	Reference to the encounter where the procedure occurred.
`encounter`	`reference`	Encounter reference identifier.	Required	1..1	Example: Encounter/Encounter-805.
`performedDateTime`	—	Date and time when the procedure was performed.	Required	1..1	Must include timezone. Represents start date and time of procedure. Anesthesia CPT codes must use performedPeriod instead, with both start and end times required.
`recordedDate`	—	Date and time when the procedure was recorded in the system.	Optional	0..1	Represents documentation timestamp for the procedure.
`reasonReference`	—	Condition or diagnosis associated with the procedure.	Conditional	0..*	Used when a procedure is associated with a diagnosis or condition.
`reasonReference`	`reference`	Reference to the related condition.	Conditional	0..1	Example: Condition/ConditionID. Added to procedure in superbill context.

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)