Claims Out Integration Point
The Claims application provides the capability to get Claims Out to support the external services that require the full details of a claim, as in the claims transaction repository, in the following ways:
-
Claims Out integration point to get details of a single claim (online).
-
Claims Out Activity to get a file-based delivery for multiple claims.
The finalized claim is stored in the Claims Transaction Repository (CTR), a flatter structure designed to support external systems. Requests to the IP activity can result in a working copy claim and/or a claim transaction (a copy from the CTR). Returning a working copy claim transforms into a claim transaction without a version.
In effect, it is a preview of what the claim transaction for the claim would be if it were finalized at the time of the request. This transformation is done using a transaction creation scenario in the same way as creating a claim transaction when finalizing a claim. For descriptions of the differences between the working copy and the claim transaction model, as well as details on transaction creation scenarios, see the Data Model chapter from Operations Guide for more details.
Claims Out Integration Point
Request
An external system performs the following GET
request to get claim details:
http://[hostName]:[portNumber]/[api-context-root]/claimstransactionout/{claimcode}.
Claims application provides with one of the following responses:
-
The highest CTR version claim: If the claim is currently finalized.
-
The working copy: If the claim still needs to be finalized (that is, the claim has never been finalized or has been un-finalized and yet to be re-finalized).
An external system can request a specific version of the claim by specifying the Version path parameter.
To clarify, consider the following GET
request:
http://[hostName]:[portNumber]/[api-context-root]/claimstransactionout/{claimcode}/3
This returns the CTR version number 3.
It is possible to make a request for all the claim versions (including the working copy versions of claims that are now un-finalized or have never been finalized) using the following GET
request:
http://[hostName]:[portNumber]/[api-context-root]/claimstransactionout/{claimcode}/all
Here, it is possible to limit the versions of a claim by providing a data range.
- dateFrom -
-
-
If specified, it filters the selection of claim versions to those with a transaction date on or after
datefrom
. -
It also considers a working copy claim created or the last updated on or after
datefrom
.
-
- dateTo -
-
-
If specified, it filters the selection of the claim versions to those with a transaction date up to and including
dateTo
. -
It also considers a working copy claim created or the last update up to and including
dateto
.
-
The external system can provide finalizedonly
query parameter to further filter out the contents of the response.
This query parameter is available for the paths /{claimcode}
and /{claimcode}/all
:
Parameter | Description |
---|---|
|
Limits the selection to finalized claim versions. For example, when making a request with a |
The use of finalizedonly
makes the following options possible:
Request | With Query Parameter finalizedonly |
Output |
---|---|---|
…/{claimcode} |
|
Return the highest CTR version for the claim. Nothing is returned for claims that have never been finalized. Return the highest CTR version even for claims that are un-finalized. |
…/{claimcode} |
|
|
…/{claimcode}/2 |
Not Applicable |
This request returns a specific CTR Version of the claim. |
…/{claimcode}/all |
|
Return all the finalized versions of claim (that is, working copy Version will not be returned if a claim is currently un-finalized or has never been finalized). |
…/{claimcode}/all |
|
Return all the versions of a claim including a working copy Version for un-finalized and never finalized claims. |
…/{claimcode}/all?datefrom=YYYY-MM-DD&&dateto=YYYY-MM-DD |
|
Return all the versions of a claim including a working copy Version for un-finalized and never finalized claims that meet the date range selection criteria. |
…/{claimcode}/all?datefrom=YYYY-MM-DD&&dateto= YYYY-MM-DD |
|
Return all the finalized versions of a claim that meet the date range criteria. |
The external system can also ask if the reversal transaction needs to be excluded or only the reversal transaction is needed by using the reversaloption
query parameter.
This parameter is available for /{claimcode}/{version}
and /claimcode/all
paths.
By default, the system always includes reversal (when available).
Parameter | Description |
---|---|
reversaloption |
If If |
Response
The system returns the following response:
<claimsTransactionOutResponse> -- for details refer section Claims Transaction Response
In case of errors, see Response Messages for more details.
The following message can occur in the response:
Code | Sev | Internal message |
---|---|---|
CTR-IP-CLTO-001 |
Fatal |
|
CTR-IP-CLTO-002 |
Fatal |
Claim with the claim code as {code} does not exist. |
CTR-IP-CLTO-003 |
Fatal |
The integration point claimsOut is not supported for Large Claims. Make use of the Claims Out Activity. |
GEN-PROC-003 |
Fatal |
No applicable CTR transaction scenario was found for claim with code |
For Large Claims, the application does not support the Claims-Out using the integration point considering the size of the response. |
For sub-claims, a claims-out-integration point works similarly to a standard claim. |
Claims Out Activity
This activity delivers requested claim transactions by placing them in a data file. Claim transactions are returned grouped by claim code and version in the <claims> element. description of the message format is in the section Claims Transaction Response.
This activity type has the following parameters:
Name | Description |
---|---|
Claim Code |
List of semi-colon-separated claim codes. |
Service Entity Type |
|
Service Entity Code |
|
Include Finalized Only |
If specified as |
Include All Version |
If specified as
If specified as
|
Reversal Option |
If If |
It is mandatory to provide at least one selection criterion from the claim code or serviced entity.
|
Messages
The following messages can occur during this activity.
Code | Sev | Internal Message |
---|---|---|
CTR-ACT-CLTO-001 |
Fatal |
Serviced entity code {code} with type {code} is unknown. |
CTR-ACT-CLTO-002 |
Fatal |
Claim with the claim code as {code} does not exist. |
CTR-ACT-CLTO-003 |
Fatal |
It is mandatory to specify at least one selection criterion (claim code/date range/serviced entity). |
CTR-ACT-CLTO-004 |
Fatal |
The claims-out activity does not support the combination of large claims and regular claims. |
GEN-PROC-003 |
Fatal |
No applicable CTR transaction scenario was found for the claim with code |
Claims Out File Delivery Integration Point
The File Based Delivery
integration point provides an option to write all the claims transactions to a data file and make the data file available for download.
The following common notification will be sent to the configured endpoint.
The endpoint to send notifications can be configured using ohi.claimsout.datafile.notification.endpoint
.
If the endpoint requires authentication, use the authentication use case: ClaimsTransactionOutNotificationClient
to set authentication
.
See the Outbound RESTful Service Invocations section in Security Guide for the process and more properties:
<notification correlationId="" workId="{activityId}" status="">
<links>
<link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data"/>
<link rel="file" href="http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data"/>
...
</links>
</notification>
The data file can be downloaded using the following Get
request from the data file set integration point:
http://[hostName]:[portNumber]/[api-context-root]/datafilesets/{datafilesetcode}/datafile/{datafilecode}/data
This will initiate a request to download the financial message data file.
File Contents
The claims transaction out message file will have the following structure:
<claimsTransactionOutResponse> <claimList> <claim code=""> <ctrclaimList> <ctrclaim/> <ctrclaim/> </ctrclaimList> <externalClaimsData/> <financialHoldList/> </claim> ... </claimList> </claimsTransactionOutResponse>
Claims Out Response
The claims out response has the following structure:
<claimsTransactionOutResponse> <claimList> <claim code =""> <ctrclaimList> <ctrclaim> -- includes attributes from CTR Claim + status (see note below) <ctrTransactionLabelList> -- includes attributes from CTR Transaction Label <ctrStatusHistoryList> <ctrstatushistory> -- includes attributes from CTR Status History <ctrPendReasonHistoryList/> -- includes attributes from CTR Pend Reason History <ctrCalloutHistoryList/> -- includes attributes from CTR Callout History </ctrstatushistory> ... </ctrStatusHistoryList> <ctrClaimUnfinalizeReasonList> <ctrclaimunfinalizereason> -- includes attributes from CTR Claim Unfinalize Reason ... </ctrClaimUnfinalizeReasonList> <ctrClaimPolicyProductList/> -- includes attributes from CTR Claim Policy Product <financialTransaction> -- includes attributes from Financial Transactions </financialTransactionProcessData> <financialTransactionDetailList> <financialTransactionDetail> -- Claim level financial transaction details </financialTransactionDetailProcessData> </financialTransactionDetail> ... </financialTransactionDetailList> </financialTransaction> <financialHoldList> -- financial transaction level holds <financialHold/> </financialHoldList> <externalClaimsData/> <ctrClaimLineList> <ctrClaimLine/> -- includes attributes from CTR Claim Line <ctrClaimLineAppliedParameterList/> -- includes attributes from CTR Claim Line Applied Parameters <ctrClaimLineBenefitSpecificationList/> -- includes attributes from CTR Claim Line Benefit Specification <ctrClaimLineProviderPricingClauseList/> -- includes attributes from CTR Claim Line Provider Pricing Clause (i.e. "Applied provider pricing clauses") <ctrClaimLineCoverageList> <ctrClaimLineCoverage> -- includes attributes from CTR Claim Line Coverage <financialTransactionDetailList> <financialTransactionDetail> -- includes attributes from Financial Transaction Detail </financialTransactionDetailProcessData> -- includes attributes from FT Process Data + invoiceID, invoiceLineId, accountingDetailID </financialTransactionDetail> </financialTransactionDetailList> </ctrClaimLineCoverage> ... </ctrClaimLineCoverageList> <ctrClaimLineDiagnosisList/> -- includes attributes from CTR Claim Line Diagnosis <ctrClaimLineMessageList/> -- includes attributes from CTR Claim Line Message <ctrClaimLineModifierList/> -- includes attributes from CTR Claim line Modifier <ctrClaimSubLineList/> -- includes attributes from CTR Claim Sub Line </ctrClaimLine> ... </ctrClaimLineList> </ctrclaim> ... </ctrclaimList> <externalClaimsData settlementReasonCode=""> </externalClaimsData> <financialHoldList> -- claim level financialholds <financialHold/> </financialHoldList> </claim> ... </claimList> </claimsTransactionOutResponse>
Claim status will not be stored in the CTR; however, it is included in claim out <ctrclaim status>. For finalized claims (retrieved from the CTR) it always has status FINALIZED. For working copy claims that are retrieved for return via claim out, it is set to the current status of the claim. |
he mapping from a Claim to a Claim Transaction is described in Repository Model. The response includes all the attributes described in Repository Model along with the attributes related to auditing and dynamic fields or records.
Auditing Information
A number of elements in the response message include attributes that contain audit information. These attributes are:
-
createdBy
-
creationDate
-
lastUpdatedBy
-
lastUpdatedDate
The attributes createdBy
and lastUpdatedBy
specify a user login name; creationDate
and lastUpdatedDate
specify a time stamp.
Include these four attributes in the following elements:
-
ctrclaim
-
ctrclaimLine
-
message at clam
-
message at claim line level
-
diagnosis at claims
-
diagnosis at claim line level
-
subLine
-
un-finalizeReason
-
statusHistory
-
modifier
-
external claims data
The element <ctrClaim> has the additional attributes: objectLastUpdatedBy
and objectLastUpdatedDate
.
These attributes hold the user and time stamp of the last change to the claim or any underlying detail.
It is possible that the user in the audit columns no longer has an account in the Claims application. In this scenario, the ID of the account record will be returned rather than the user’s login name.
For finalized claims, the attributes' values will be drawn from the claim transaction. Values will be drawn from the working copy claim audit fields for un-finalized claims.
Dynamic Fields and Records
Extension of some entities of the repository may be with dynamic fields and dynamic records. The values for these fields and records will be included in messages in a standard. See the Concepts in the Developer Guide for more details.
External Claims Data
Claim transaction elements that are for a specific version of a claim include their version’s corresponding version-specific external claim data. Claim transaction elements that contain the working copy Version of a claim do not include any external claims data.
Claim elements contain their claim’s non-version-specific external claim data.
This structure reflects the principle that non-version-specific external claim data is relevant to all versions of a claim.
Use the same element structure in both cases (version specific and non-version-specific). The structure consists of a part for fixed attributes of external claims data, dynamic attributes, and dynamic records. Dynamic attributes and dynamic records will be included in the standard way, as mentioned above.
Returning Financial Transactions and Financial Transaction Details
Financial information can be recorded on three levels on a claim transaction and its related coverage lines:
- CTR Claim
-
Financial transactions and related financial transaction process data are related to a single claim transaction. Report these attributes in the <ctrClaim> element.
- Claim Line Coverage
-
Financial transaction details and related financial transaction detail process data can be related to a single claim line transaction. Report these attributes in the <ctrClaimLineCoverage> element within the <claimLine> element.
- Claim Transaction Level Financial Transaction Details
-
It is possible that financial transaction details are not related to a coverage claim line. Report the attributes of these financial transaction details and related financial transaction process data as a separate element in the <ctrClaim> element.
<financialTransaction/> element has the following attributes:
-
reversal
-
totalAmount
-
totalAmountCurr
<financialTransactionProcessData/> element has the following attributes:
-
dueDate
-
financialMessageMandatory
-
finMessageHandledDatetime
-
finMessageResult
-
finMessageId
-
finMessageBulkingGroup
-
internalRemarks
-
penaltyDate
-
superseded
<financialTransactionDetail/> element has the following attributes:
-
claimLineCode
-
componentCode
-
amount
-
amountCurr
-
numberOfUnits
-
productBrandCode
-
productCode
<financialTransactionDetailProcessData> element has the following attributes:
-
accountingBulkingGroup
-
counterPartyCode
-
counterPartyQualifier
-
generalLedgerAccount
-
internalRemarks
-
indInvoice
-
invoiceBulkingGroup
-
indInvoiceLineGrouping
-
indAccountDetailGrouping
-
invoiceLineBulkingGroup
-
payFromBankAccount
-
paymentBeneficiaryFlexCodeDefinitionCode
-
paymentBeneficiaryCode
-
invoiceId
-
invoiceLineId
-
accountingDetailId
Returning Financial Holds
The complete history of financial holds will be reported by this integration point. Financial holds will be reported for claim level financial holds and financial transaction level financial holds.
<financialHold/> element has the following attributes:
-
holdType
-
heldBy
-
startDatetime
-
releasedBy
-
releaseDatetime
-
expirationDatetime
-
remarks
-
releaseRemarks
Changes Related to Large Claim
Response Structure
The claims out response structure of a large claim is as follows:
<claimsTransactionOutResponse> <claimList> <claim code =""> -- large claim code <ctrclaimList> <ctrclaim> -- includes attributes from Large Claim CTR + status <ctrTransactionLabelList> -- includes attributes from large claim CTR Transaction Label <ctrStatusHistoryList> <ctrstatushistory> -- includes attributes from large claim CTR Status History <ctrPendReasonHistoryList/> -- includes attributes from large claim CTR Pend Reason History </ctrstatushistory> ... </ctrStatusHistoryList> <ctrClaimUnfinalizeReasonList> <ctrclaimunfinalizereason> -- includes attributes from large claim CTR Claim Unfinalize Reason ... </ctrClaimUnfinalizeReasonList> <ctrClaimPolicyProductList/> -- includes attributes from large claim CTR Claim Policy Product <ctrClaimLineList> <ctrClaimLine/> -- includes attributes from Sub-Claims CTR Claim Line <ctrClaimLineAppliedParameterList/> -- includes attributes from Sub-Claims CTR Claim Line Applied Parameters <ctrClaimLineBenefitSpecificationList/> -- includes attributes from Sub-Claims CTR Claim Line Benefit Specification <ctrClaimLineProviderPricingClauseList/> -- includes attributes from Sub-Claims CTR Claim Line Provider Pricing Clause (i.e. "Applied provider pricing clauses") <ctrClaimLineCoverageList> <ctrClaimLineCoverage> -- includes attributes from Sub-Claims CTR Claim Line Coverage <financialTransactionDetailList> <financialTransactionDetail> -- includes attributes from Financial Transaction Detail </financialTransactionDetailProcessData> -- includes attributes from FT Process Data + invoiceID, invoiceLineId, accountingDetailID </financialTransactionDetail> </financialTransactionDetailList> </ctrClaimLineCoverage> ... </ctrClaimLineCoverageList> <ctrClaimLineDiagnosisList/> -- includes attributes from Sub-Claims CTR Claim Line Diagnosis <ctrClaimLineMessageList/> -- includes attributes from Sub-ClaimsCTR Claim Line Message <ctrClaimLineModifierList/> -- includes attributes from Sub-Claims CTR Claim line Modifier <ctrClaimSubLineList/> -- includes attributes from Sub-Claims CTR Claim Sub Line </ctrClaimLine> ... </ctrClaimLineList> </ctrclaim> ... </ctrclaimList> <externalClaimsData -- includes large claim CTR external data settlementReasonCode=""> </externalClaimsData> </claim> ... </claimList> </claimsTransactionOutResponse>
The following example scenarios will help you understand the CTR mappings and Claims Out response of a large claim.
Consider a large claim split into three sub-claims:
-
Sub-claim 1
-
Sub-claim 2
-
Sub-claim 3
Let us say that the large claim and each of its sub-claims are in finalized status. Sub-claim 1 and 2 have one finalization, and sub-claim 3 has two finalizations.
Let us say that the large claim is un-finalized and finalized again. As part of the large claim finalization, sub-claim 1, sub-claim 2, and sub-claim 3 have one finalization.
Scenario 1: Claims-Out Response for a Large Claim (Finalized only, all versions set to no
and reversal indicator not specified).
![Claims Out Integration Point](../_images/claims-out-activity-scenario1.png)
Scenario 2: Claims-Out Response for a Large Claim (Finalized only, all versions set to no
and reversal set to E
).
![Claims Out Integration Point](../_images/claims-out-activity-scenario2.png)
Scenario 3: Claims-Out Response for a Large Claim (Finalized only, all versions set to yes
and reversal not specified).
![Claims Out Integration Point](../_images/claims-out-activity-scenario3.png)
Scenario 4: Claims-Out Response for a Large Claim (Finalized only, all versions set to yes
and reversal set to E
).
![Claims Out Integration Point](../_images/claims-out-activity-scenario4.png)
Consider the large claim is un-finalized, and sub-claim 3 has one more finalization.