API Definition & Example
Following is an example of an API definition. It serves as a starting point for implementers to understand what they may wish to publish to vendors in order to integrate. Additional custom HTTP request and response headers may be added.. A trace number or other sender/source details may also be desired.
Claim/$submit and Claim/$reversal
This is an example of a FHIR defined Operation that can be used to support Claim Related Requests, which are the Claim Request - Dispense and Professional Services as well as the Claim Reversal Transaction.
| Overview | Detail | ||
|---|---|---|---|
| API Type | REST | ||
| Verb | POST | ||
| Request Content Type | JSON: application/fhir+json | ||
| Response Content Type | JSON: application/fhir+json | ||
| Required Request Headers | Accept: application/fhir+json; fhirVersion= 4.0.1 | ||
| Description | Service to process FHIR Dispense claim, Professional Services claim or Claim Reversal request This is a message bundle, with a Message Header.focus=claim. The exact transaction will be determined by the Message Header.event id which is used to specify the transaction type. This is a Request-reply pattern that returns a claim or reversal response. |
||
| Request Profiles | Claim/$submit Claim/$reversal Production Endpoint URL eg https://EnvironmentSpecificHost/EnvironmentPath/api/xml/eClaimsRequest/claim/$submit Endpoint will be published by each implementer and will be specific to the Claims Switch or Adjudicator and Environment (Production or Test) |
||
| Service Response HTTP Code header and Payload | HTTP 200 for success + response payload as FHIR bundle HTTP 400 for bad requests + payload as OperationOutcome bad request format or FHIR request message validation failure or processing faliure due to bad data HTTP 401 for authentication failure HTTP 500 for any backend errors + payload as OperationOutcome with error level issue |
||
| Service Response HTTP Header | Values may include reference numbers or other key data as defined by the implementer | ||
| FHIR Header Values: |
fhir-message-bundle-id: An identifier that specifies the version of the application that processed the request. For example, fhir-message-request-id: The FHIR message header ID of the request. This may not be defined if the input FHIR request is not valid. fhir-message-response-id: The HL7 response ID. This may not be defined if the HL7 response does not contain an ID. |
||
| Authentication Header Values - example only: | authentication-username: The username that was authenticated. authentication-token: The token that was authenticated. This may be different than the one passed into the request if the authenticator is configured to generate a new token for each request. authentication-state: The authentication state. SERVER_ERROR, ACCOUNT_LOCKED_TEMP__TRY_AGAIN_LATER, AUTHENTICATED, AUTHENTICATION_FAILED, USERNAME_TOKEN_MISSING, USERNAME_MISSING, TOKEN_MISSING, USERNAME_TOKEN_MISMATCH, TOKEN_INVALID, TOKEN_EXPIRED authentication-details: If more details are required such as for state ACCOUNT_LOCKED_TEMP_TRY_AGAIN_LATER, this contains them. authentication-tokenCreationDate: The creation date of the token, in ms since EPOCH. authentication-tokenExpiryDate: The expiry date of the token, in ms since EPOCH |
||
| fhir-message-response-status: | The status of the response. The option are SUCCESS or FAILURE. |
||
| Detected Issues Header Value | detectedIssue-errorCode: The ERROR_CODE that denotes the issue. detectedIssue-errorMessage: If an issue is detected, this will be the message to describe the issue. detectedIssue-userReason_#: If an issue is detected, and if there are more detailed reasons for an error, they will be provided in the header. Each reason will be in its own HEADER value. Example: detectedIssue-userReason_1: bad format of FHIR request detectedIssue-userReason_2: FHIR request is missing fields |
$daily-totals
This capability is invoked using the $daily-totals* Operation. The operation is invoked using an HTTP POST and the result set with either be an OperationOutcome (if there were errors) or a Bundle, Message Header + Parameters:Out instance containing the result set.
| Overview | Details |
|---|---|
| API Type | REST |
| Verb | POST |
| Request | Content Type: JSON: application/fhir+json |
| Response | Content Type: JSON: application/fhir+json |
| Required Request Headers | Accept: application/fhir+json; fhirVersion= 4.0 |
| Description | Service to process FHIR request for Daily Totals, including a Parameters resource. This is a Request for the Accumulated Totals for a specific adjudication date, and if specified, a list of Carriers and/or Group ID's to be included or excluded, as indicated in the request. |
| Endpoint URL https://EnvironmentSpecificHost/EnvironmentSpecificPath/api/xml/eClaimsRequest/[base]/$daily-totals *NOTE: Endpoint will be published by each implementer prior to vendor testing and will be specific to the Claims Processor/Switch/Adjudicator |
|
| Service Response HTTP Code header and Payload | HTTP 200 for success + response as FHIR Parameters resource HTTP 400 for bad requests + payload as OperationOutcome bad request format or FHIR request message validation failure or processing faliure due to bad data HTTP 401 for authentication failure HTTP 500 for any backend errors + payload as OperationOutcome with error level issue |
| Service Response HTTP Header Values | all to be discussed as per above Operation |
$adjudication-details
**Insert Content TBD, after review of the above.
ADD STUFF HERE
HTTP Headers - supporting info only, can be removed after review
The FHIR specification makes use of several HTTP headers to change the processing or format of requests or results, (https://build.fhir.org/http.html#Http-Headers). Following are the HTTP Headers that will be used within this specification, as seenin the API Definitons above.
As above - once review is complete the content will be extended here as well