FHIR Messaging

Overview

The Netsmart General Purpose FHIR R4 API provides FHIR Messaging capabilities through the Process Message operation. FHIR Messaging enables asynchronous communication between healthcare systems using standardized message events and structured payloads.

Before implementing messaging, validate current capabilities by retrieving the CapabilityStatement:

GET {base-url}/metadata

Check the messaging section for supported message events and endpoints.

Message Schema

All FHIR messages follow a standardized structure:

{
  "resourceType": "Bundle",
  "type": "message",
  "entry": [
    {
      "resource": {
        "resourceType": "MessageHeader",
        "eventCoding": {
          "system": "http://ntst.com/fhir/message-events",
          "code": "{event-type}"
        },
        "focus": [
          {
            "reference": "{primary-resource}"
          }
        ]
      }
    }
    // Additional resources...
  ]
}

Operations

Process Message

Endpoint: POST {base-url}/$process-message

Purpose: Submit FHIR messages for processing

Authorization: Requires appropriate messaging scopes based on message type

Parameters:

Parameter	Type	Required	Description
Bundle	Resource	Yes	Message bundle containing MessageHeader and related resources

Supported Message Events

Netsmart-defined Message Events

All Netsmart-defined messaging events use the system: http://ntst.com/fhir/message-events

Name	Type	Description	Supported Solutions
Submit Service Request	submit-service-request	Submit referrals to Referral Manager	Referral Manager
Update Service Request	update-service-request	Update existing referrals in Referral Manager	Referral Manager

Examples

Basic Message Submission

# Production
curl -X POST 'https://fhir.netsmartcloud.com/v4/$process-message' \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/fhir+json" \
  -d @message-bundle.json

# Preview
curl -X POST 'https://fhirtest.netsmartcloud.com/v4/$process-message' \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/fhir+json" \
  -d @message-bundle.json

Response Handling

Successful message processing returns a Bundle with:

• MessageHeader with response details
• Created/updated resources with assigned IDs
• OperationOutcome for any warnings or information

Integration Patterns

Message Workflow

1. Prepare Message Bundle

   • Create MessageHeader with appropriate event type
   • Include all required resources
   • Validate against supported profiles

2. Submit Message

   • POST to /$process-message endpoint
   • Include proper authorization headers
   • Handle response appropriately

3. Process Response

   • Check MessageHeader response code
   • Extract created resource IDs
   • Handle any errors or warnings

Error Recovery

• Implement retry logic for transient failures
• Validate message structure before submission
• Monitor response codes and OperationOutcome details

Relationships to Other Resources

• Process Message Operation - Core messaging operation
• MessageHeader Resource - Message header structure
• Bundle Resource - Message container format

Error Handling

For comprehensive error handling information, see Common Errors.

Support

For technical support with FHIR messaging:

• Contact: Netsmart Technologies, Inc.
• Documentation: Process Message Operation
• Examples: Individual message event documentation