AdvaView Interface Specification

Launching AdvaView

AdvaView is a web-based diagnostic viewer directly integrated with AdvaPACS. It provides a comprehensive solution for viewing and analyzing diagnostic images, including mammographic images, and is FDA cleared for diagnostic use. Additionally, it is CE Class IIb certified as a medical device suitable for review purposes or primary diagnosis.

This guide provides instructions on launching the AdvaView viewer from third-party applications, including HIS and RIS systems.

AdvaHealth provides two methods of launching AdvaView:

• Third-party generated tokens matching the authentication token specification described in Token Generation
• Tokens generated for third-party systems by AdvaPACS

---

Token Generation

Whether done by AdvaPACS or by the third-party customer, the viewer launch token must take one of the following forms depending on whether the viewer is launched from a set of studies, by Study Instance UIDs, or by Patient ID with accession numbers. All tokens must be signed with the SHA-256 hash of the customer's API key access secret.

By Study Instance UID

{
  "jti": "<unique token identifier>",
  "expiresAt": "<epoch seconds>",
  "userName": "<advapacsUserName>",
  "studies": [
    {
      "studyInstanceUid": "1.2.3.4.6"
    }
  ],
  "dataSourceId": "optional-data-source-id",
  "version": 1
}

Field	Required	Notes
jti	Yes	Unique token ID — opaque string, not required to be a UUID. One-time use.
expiresAt	Yes	Epoch seconds. Max 30 seconds in the future.
username	Yes	Must be a valid, enabled AdvaPACS user with viewStudyImage permission.
studies	Yes	Array of study objects.
studies[].studyInstanceUid	—	Use this or accessionNumber, never both on the same entry. Must be a valid DICOM UID.
studies[].dataSetId	No	Per-study override for dataset.
dataSourceId	No	Token-level default; falls back to AdvaPACS.
version	No	Defaults to 1.

By Patient ID and Accession Number

{
  "jti": "<unique token identifier>",
  "expiresAt": "<epoch seconds>",
  "userName": "<advapacsUserName>",
  "studies": [
    {
      "accessionNumber": "614485-US"
    }
  ],
  "patientId": "ABC123",
  "dataSourceId": "optional-source-id",
  "version": 1
}

Field	Required	Notes
jti	Yes	Unique token ID — opaque string, not required to be a UUID. One-time use.
expiresAt	Yes	Epoch seconds. Max 30 seconds in the future.
username	Yes	Must be a valid, enabled AdvaPACS user with viewStudyImage permission.
studies	Yes	Array of study objects.
studies[].accessionNumber	—	Plain, HL7 EI, or FHIR token param formatted.
patientId	Conditional	Required when identifying studies by accession number.
dataSourceId	No	Token-level default; falls back to AdvaPACS.
version	No	Defaults to 1.

Note: Tokens cannot supply both Study Instance UIDs and Patient IDs/Accession Numbers. One method must be used during token creation.

JWT Header

All token requests must contain the following JWT header. The kid value is the Access Key ID created when registering an API key with the PACS:

{
  "alg": "HS256",
  "typ": "JWT",
  "kid": "Access Key ID"
}

Launch URL

Token generation should produce the following launch URL. When using AdvaPACS for token generation, this URL is returned in the response:

https://<region>.advaview.advapacs.com/?token=<jwt>

Token Signing

The token must be signed using the selected HMAC algorithm with the Base64-decoded value of the API Key Access Key Secret as the signing key. Example token:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjczZGU2MGIyODhhMDQwOWNiNWYxN2M5YWM2OGVlODJkIn0.eyJqdGkiOiJ1bmlxdWUtdG9rZW4taWQiLCJleHBpcmVzQXQiOjE3NTIwMDAwMzAsInVzZXJuYW1lIjoiZXhhbXBsZS51c2VyIiwic3R1ZGllcyI6W3siYWNjZXNzaW9uTnVtYmVyIjoiNjE0NDg1LVVTIn1dfQ.signature

---

Independent Third-Party Launch

When launching the viewer without requiring AdvaPACS to generate a launch token, the third-party system must generate the token according to the specification described in Token Generation and construct the correct URL format.

---

AdvaPACS-Generated Token Launch

Rather than generating a token independently, third-party systems can create a viewer launch URL through AdvaPACS. This integration requires a registered API key for AdvaPACS with the generateViewerToken permission assigned.

Authorization Header

Authorization: ID=<Access Key ID>,Secret=<Access Key Secret>

Request URL

POST https://<region>.api.integration.advapacs.com/viewer/launch

Viewer Types

When calling the integration endpoint, customers must specify the type of viewer to launch. For AdvaView, two options are available:

Value	Description
standard	Standard viewer
diagnostic	FDA-cleared diagnostic viewer

Request Body — By Study Instance UID

{
  "viewer": "standard",
  "username": "example.user",
  "studyInstanceUid": ["1.2.840.10008.5.1.4.1.1.2.1"],
  "dataSetId": "optional-data-setId"
}

Request Body — By Patient ID and Accession Numbers

{
  "viewer": "standard",
  "username": "example.user",
  "patientId": "ABC123",
  "accessionNumber": ["614485-US", "614486-US"]
}

Validation Rules

Rule	Detail
studyInstanceUid and patientId/accessionNumber are mutually exclusive	Never include both in the same request.
patientId requires accessionNumber	Neither is valid without the other.
dataSetId must be a valid UUID	If omitted, defaults to the API key's default dataset.

Successful Response

On a successful request, AdvaPACS returns:

{
  "url": "https://<subdomain>.advaview.advapacs.com/Viewer/?token=<jwt>"
}

The jwt value matches the token format described in Token Generation.