Skip to main content

HL7 Over HTTPS

AdvaPACS supports exchanging HL7 messages over HTTPS using a REST-based interface. This allows external systems to send HL7 messages to AdvaPACS and retrieve outbound messages using authenticated HTTP requests.

This page describes how to configure an HL7 over HTTPS service, create the required API credentials, and interact with the service using the available endpoints.

Creating an HL7 over HTTPS Service​

Before sending or retrieving HL7 messages over HTTPS, an HL7 service and API key must be created in AdvaPACS.

Create the HL7 Service​

  1. Navigate to Configuration → HL7/FHIR and select either Inbound or Outbound dependant on what is required.
  2. Click the + icon to create a new HL7 service:
  1. Set Type to HL7 Over HTTPS.
  2. Enter a Name for the service.
  3. Configure the message log retention period for successful and failed messages.
  4. Select the Default Timezone to use when an HL7 message does not include a timezone offset.
  5. Add any required Whitelist IPs.
  6. Select the latest Interface Version.
  7. Click Create.

Once the service has been created, open it and copy the Service URL. This URL is used by external systems to send and retrieve HL7 messages over HTTPS.

Create an API Key​

An API key is required to authenticate requests to the HL7 over HTTPS service.

  1. Navigate to Configuration.
  2. Open the API Keys menu.
  3. Click the + icon to create a new API key.
  4. Enter a Name for the API key.
  5. Select HL7 Services under the available permissions.
  6. Grant the API key access to the HL7 over HTTPS service created earlier.
  7. Configure an expiry date if required.
  8. Click Create.
  9. Copy the API Key ID and API Key Secret. The secret is only displayed once when the API key is created.

The integrating application requires the following information:

  • Service URL
  • API Key ID
  • API Key Secret

These credentials are included in the Authorization header of every request.

Authorization: ID={{APIKeyID}},Secret={{APIKeySecret}}

Sending HL7 Messages​

HL7 messages are sent to AdvaPACS using an authenticated POST request. The request body contains the HL7 message, while the request headers specify the message format and desired response format.

POST /hl7/services/<Service ID> HTTP/1.1
Host: <Region>.api.integration.advapacs.com
Authorization: ID={{APIKeyID}},Secret={{APIKeySecret}}
Content-Type: application/hl7-v2+er7
Accept: application/hl7-v2+er7, application/json

The request body should contain a complete HL7 message. AdvaPACS supports both HL7 ER7 and HL7 XML message formats. The Content-Type and Accept headers should be set to match the format of the message being sent.

Message FormatContent-TypeAccept
HL7 ER7application/hl7-v2+er7application/hl7-v2+er7, application/json
HL7 XMLapplication/hl7-v2+xmlapplication/hl7-v2+xml, application/json

For successful requests, AdvaPACS returns an HL7 ACK using the format specified in the Accept header. If the request cannot be processed by the API (for example, due to invalid authentication or an invalid request), an appropriate HTTP status code is returned together with a JSON error response.

Retrieving Outbound Messages​

Outbound HL7 messages are retrieved by sending a GET request to the configured HL7 service. The endpoint acts as a message queue, allowing client applications to periodically poll for new outbound messages.

If a message is available, AdvaPACS returns the HL7 message in the response body along with an x-outbound-message-id response header. This header uniquely identifies the queued message and must be used when acknowledging the message after it has been processed.

GET /hl7/services/<Service ID>/messages HTTP/1.1
Host: <Region>.api.integration.advapacs.com
Authorization: ID={{APIKeyID}},Secret={{APIKeySecret}}

Once the message has been processed successfully, acknowledge it by sending a POST request to the acknowledgement endpoint using the returned x-outbound-message-id.

POST /hl7/services/<Service ID>/messages/<x-outbound-message-id> HTTP/1.1
Host: <Region>.api.integration.advapacs.com
Authorization: ID={{APIKeyID}},Secret={{APIKeySecret}}
Content-Type: application/json

The body of the message shall be:

{
  "success": true,
  "errorMessage": ""
}

A successful acknowledgement returns HTTP 200 OK and removes the message from the outbound queue.