API Definition & Example
Following is an example of an API definition. It serves as a starting point for implementers to be as consistent as possible when they publish their APIs to vendors for integration. Additional custom HTTP request and response headers may be added. For example, a trace number or other sender/source details may also be desired.
Claim/$submit
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 (if separation desired ) 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