PAS Subscription FHIR API Specification
Service Overview
InterSystems PAS (Prior Authorization Support) FHIR APIs are designed in compliance with the CMS-0057-F regulationsOpens in a new tab.
Refer to the Getting Started section for information on connectivity, authentication and how to get help. To use the FHIR APIs, you will need to know the base URL of the FHIR server you will be connecting to. You can also retrieve the capability statement for the service.
A provider can use the PAS Subscription API to register themselves with a payer to receive notifications when certain claims are updated. This request is sent as a FHIR Subscription resource. The provider can subsequently check the status of any subscriptions by using the $status endpoint of this API. A provider can also use this API to update an existing subscription.
Once a subscription has been created for a provider, if the payer puts one of a their claims into a pended status, meaning that they require more time or further information in order to make an adjudication, when the claim is no longer pended, the payer will send a FHIR Subscription Notification Bundle to the provider including that claim. The provider can then submit a $inquireOpens in a new tab request to obtain the latest information for the claim.
This API has been implemented in compliance with the FHIR R4 Subscription APIOpens in a new tab, incorporating the FHIR Subscriptions R5 BackportOpens in a new tab framework.
Workflow
A typical workflow involving the Subscription operation might be:
-
The provider posts a Subscription request with a payer, registering their organization identifier and their endpoint that should receive notifications
-
The payer’s system confirms the subscription has been created
-
The provider submits a claim to the payer, including the claim identifier and their organization identifier in the request
-
For a claim that has previously been pended, when the payer updates the claim so that it is no longer pended, they trigger a notification to the provider in the form of a FHIR Subscription Notification Bundle
-
The provider uses the claim identifier from the notification and submits a $inquire request to the payer to get the claim’s latest information
-
The payer's system responds with information about the claim
Endpoint: Subscription
URL
The URL for this API when creating a subscription is:
<BaseURL>/Subscription
Once you have created a subscription, you can use its identifier in the API’s URL to update it:
<BaseURL>/Subscription/<id>
Optional Capabilities
None.
Endpoint Prerequisites
None.
Required Header Settings
-
Content-Type: application/json+fhir
-
Accept: application/json+fhir
Request Methods
Invokes Subscription with the specified PAS Subscription resource.
This method should be called synchronously.
Query Parameters
None.
Request Body
The body of the request is the FHIR Subscription resourceOpens in a new tab. The request must contain the value of the provider’s organization identifier which they need to include when submitting claims in the future, and the endpoint that subscription notifications will be sent to.
The value of status for the initial creation request must be “requested”.
Here is an example request:
{
"resourceType": "Subscription",
"meta": {
"profile": [
"http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
]
},
"status": "requested",
"reason": "Topic-Based Subscription for PAS",
"criteria": "http://hl7.org/fhir/us/davinci-pas/SubscriptionTopic/PASSubscriptionTopic",
"_criteria": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "ClaimResponse?identifier=<org identifier>"
}
]
},
"channel": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
"valueUnsignedInt": <value>
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
"valueUnsignedInt": <value>
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
"valuePositiveInt": <value>
}
],
"type": "rest-hook",
"endpoint": "https://example.com",
"payload": "application/fhir+json",
"_payload": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
"valueCode": "id-only"
}
]
}
}
}
A provider can update their subscription resource by sending a similar request using an HTTP POST request to <BaseURL>/Subscription/<id> using the identifier of their subscription in the URL, as well as in the request body. The value of status should be “requested” to reactivate a subscription if it has been turned off by the server you are connecting, for example, because of multiple previous notification failures. If the provider no longer wishes to receive notifications, sending a request with a status of “off” will discontinue them.
Here is an example of a request with requested status to update an existing subscription:
{
"resourceType": "Subscription",
"id": "<subscription identifier>",
"meta": {
"profile": [
"http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-subscription"
]
},
"status": "requested",
"reason": "Topic-Based Subscription for PAS",
"criteria": "http://hl7.org/fhir/us/davinci-pas/SubscriptionTopic/PASSubscriptionTopic",
"_criteria": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-filter-criteria",
"valueString": "ClaimResponse?identifier=<org identifier>"
}
]
},
"channel": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-heartbeat-period",
"valueUnsignedInt": <value>
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-timeout",
"valueUnsignedInt": <value>
},
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-max-count",
"valuePositiveInt": <value>
}
],
"type": "rest-hook",
"endpoint": "https://example.com",
"payload": "application/fhir+json",
"_payload": {
"extension": [
{
"url": "http://hl7.org/fhir/uv/subscriptions-backport/StructureDefinition/backport-payload-content",
"valueCode": "id-only"
}
]
}
}
}
Success Response
The subscription was created.
The response headers will contain “LOCATION=<URL of the new subscription>”.
Error Responses
An error due to a bad request. The response body contains a FHIR OperationOutcome resource with further details.
If the identifier parameter stored in _criteria.extension[x].valueString does not match the provider_identifier property of the OAuth 2.0 token, the error text will state “Provider organization identifier of the new Subscription does not match the 'provider_identifier' claim of the OAuth 2.0 token”.
The authenticated user does not have access to a resource needed to process the request.
The authenticated user is not authorized to use the requested resource.
An error due to missing authorization data or failed authorization.
The server cannot process the request because the media type provided in the Accept or Content-Type headers of the request is not acceptable.
A generic error message, returned when no more specific message is suitable.
Endpoint: Subscription/$status
URLs
The $status endpoint can be called in one of two ways:
-
<BaseURL>/Subscription/$status
-
<BaseURL>/Subscription/<id>/$status
Optional Capabilities
None.
Endpoint Prerequisites
The requesting provider must have previously created a subscription.
Required Header Settings
-
Accept: application/json+fhir
Request Methods
Invokes Subscription/$status operation
This method should be called synchronously.
Query Parameters
The operation supports the following input parameters:
-
id
-
status (possible values are: active, error, off, requested)
The parameters can contain a comma separated list of values.
Query parameters are ignored when using the $status instance operation.
Request Body
None.
Success Response
The body of the response is a FHIR R4 Notification: Id OnlyOpens in a new tab Bundle with a type of “query-status”.
Error Responses
An error due to a bad request. Possible causes include:
-
Provider called the operation but has not created a subscription.
-
Provider call the operation without a provider_identifier claim specified.
-
Unsupported query parameter.
-
Invalid JSON structure.
The authenticated user does not have access to a resource needed to process the request.
The authenticated user is not authorized to use the requested resource.
An error due to missing authorization data or failed authorization.
The server cannot process the request because the media type provided in the Accept or Content-Type headers of the request is not acceptable.
A generic error message, returned when no more specific message is suitable.