Claims Update Integration Point
This chapter describes the Claims Update Integration Point. The purpose of this integration point is to support claim edits through a web service call, that is, automatically and without the need for manual intervention.
Design Choices
This integration point can update claims that are either in the Change, Entry, Manual Pricing, Manual Pricing Adjudication, Pricing Finalized, Manual Benefits, Manual Adjudication or Finalized status. For updating pricing finalized or finalized claims one or more un-finalize reasons should be provided.
This integration point supports the updating claims, and the updating, adding and removing of claim lines. This integration point does not support the creation of new claims, nor the removal of existing claims.
Existing claims and claim lines will be identified and matched by their code. Assume that the service or component that sends the claim update request knows the codes of the existing claim and claim lines that need to be updated or - for claim lines only - deleted:
-
Specifying a claim code that does not exist will result in a fatal message.
-
Specifying a claim line code that does not exist will create a new claim line.
Upon specifying a list element in the request message, all existing list details will be replaced by the list details specified in the request messages. For example, if the update specifies a diagnoses element on the claim line, replace the complete existing list of claim line diagnoses. Existing claim lines will be exempted from this functionality and will only be deleted if this is specified explicitly. The messages list element features an option to retain existing message instead of replacing them.
This integration point can be used to mark claim lines as replaced by other claim lines. It also allows edits to process fields.
An update request indicates that a claim should be re-submitted after doing the update. Re-submitting the claim through this integration point triggers the exact same process as re-submitting a claim manually.
High Priority Claims
It is possible to mark a claim as high priority, meaning it will be picked up for processing with the highest priority possible. All submits for processing from the UI will automatically result in those claims getting picked up with the highest priority because an operator is waiting for the results. For a claim that is updated through the IP, it’s a choice: normally no high priority will be needed, but there could be exceptions.
Claims Update Request
The claims update request message must be sent as HTTP PUT to the URI:
-
http://[hostName]:[portNumber]/[api-context-root]/claimsupdate/{claimCode} to only update
-
http://[hostName]:[portNumber]/[api-context-root]/claimsupdate/{claimCode}/submit to update and submit claims for processing
The request message has the following structure:
<claim authorizationCode claimDate dataAccessGroupCode dueDate expirationDate externalRemarks emergency externalPricing externalBenefits highPriority overwriteMessages preprocessingDone pricingDone sendOutForPreprocessing sendOutForPricing locationTypeCode nextPayerCode paidDate precedingPayerCode priceDate providerEntityReference providerReference receiptDate serviceSpecialtyCode type claimSetCode > <claimDiagnosisList/> <claimMessageList/> <claimPendReasonList/> <claimTagActionList/> <claimUnfinalizeReasonList/> <claimantProvider/> <claimantRelation/> <locationProvider/> <paymentBeneficiaryProvider/> <paymentBeneficiaryRelation/> <paymentReceiverProvider/> <paymentReceiverRelation/> <paymentSpecificationReceiverProvider/> <paymentSpecificationReceiverRelation/> <referralProvider/> <serviceProvider/> <claimLineList/> </claim>
The following snippet contains the claim line structure:
<claimLine allowedNumberOfUnits authorizationCode authorizationExceptionType benefitsAgeInputDate benefitsInputDate claimedNumberOfUnits code delete emergency encounter episodeIdentifier endDate keepBenefits keepPricing locationTypeCode overwriteMessages originalClaimLineCode priceInputDate priceInputNumberOfUnits pricePrincipalProcedure1 pricePrincipalProcedure2 pricePrincipalProcedure3 processAsIn providerEntityReference providerReference releaseOverride replacementClaimLineCode reservationCode reservationLineCode sequence serviceSpecialtyCode startDate unlock waitingPeriodInputDate > <allowedAmount/> <benefitsInputAmount/> <benefitsProvider/> <claimedAmount/> <claimLineContractReferenceList/> <claimLineDiagnosisList/> <claimLineLimitList/> <claimLineMessageList/> <claimLineModifierList/> <claimLineOverride/> <claimLineParameterList/> <claimLinePendReasonList/> <claimSubLineList/> <locationProvider/> <paymentReceiverProvider/> <paymentReceiverRelation/> <precedingPayerPaidAmount/> <priceIndividualProvider/> <priceOrganizationProvider/> <procedure/> <procedure2/> <procedure3/> <referralProvider/> <serviceProvider/> </claimLine>
Consider the following snippet to understand the diagnosis element structure:
<claimDiagnosisList> <claimDiagnosis sequence typeCode/> <diagnosis code flexCodeDefinitionCode/> </claimDiagnosis> </claimDiagnosisList>
Consider the following snippet to understand the message element structure:
<claimMessageList> <claimMessage code origin value0 value1 value2 value3 value4 value5 value6 value7 value8 value9 transactionSourceCode referenceCode overturned /> ... </claimMessageList>
This integration point requires the correct functional identifiers for an update of a provider or serviced person or object. Use the following types to identify serviced person or object and providers.
-- example of a serviced person or object -- example of a provider <serviceProvider code flexCodeDefinitionCode />
The following snippet describes the claims tag element:
<claimTagActionList> <claimTagAction tag action> </claimTagAction> ... </claimTagActionList>
Claims Update Response
Refer to the "Response Messages" section in the HTTP API Integration Points part of the Common Features book for more details.
The system also returns a link to the status resource in the Location header when submitting a claim for processing:
Location: http://[hostName]:[portNumber]/[api-context-root]/claims//status
This enables the external system to track the progress by issuing a GET to the status URI returned in the Location header. For details on the status resource refer section "Operations" in the HTTP API chapter in the Developer Guide.
Processing
Updating Claim and Claim Lines
A field can be cleared by sending the attribute without sending a value (an empty string). Not all claim fields can be updated due to their non-transferable or technical nature. Non-updatable claim fields will not be included in the request message. After executing all updates, the claim will be saved (this is the same effect as clicking the save button in the Change Enter Claim page). If within a claim, any of the updates fail, then don’t save any updates for that claim.
The indicator changedInUi is reset (set to null) when a claim successfully updates (this indicator will be set to the value true when a claim changes in the Manual Change page after finalization; it needs to be reset if the claim afterward is updated by the Claims Update Integration Point).
Updating a field that was previously unmatched, removes the unmatched information.
Locked claim lines (if unlock is not sent in as true) cannot be updated or deleted.
A locked claim line must be first unlocked in order to update or delete it. Both the actions can be performed through a single request (unlocking to update or unlocking to delete). For example, to delete a locked claim line indicator delete and unlock both should be set to true in the request message.
Existing claim lines that have been marked as replaced, cannot be updated. However, if a replacement gets voided[1] see below because the replacing line(s) is/are removed, the previously replaced line is no longer considered replaced and may then update. Thus, it is possible to update a replaced line by specifying in the request both the update of that line as the removal of its replacing line(s).
If the update specifies an un-finalize reason element, and the claim has status Pricing Finalized, then the claim enters the level 2: un-finalize flow. If the update specifies an un-finalize reason element, and the claim has status Finalized, then the claim enters the level 2: un-finalize flow as long as there is no settlement reason specified on the external claims data; if there is a settlement reason specified on the external claims data, then the update will fail. Through the un-finalize flow, set the claim to status Change, the old un-finalize reasons will be removed, and the new un-finalize reasons will be attached to the claim. If the update specifies an un-finalize reason element, and the claim does not have the status Pricing Finalized or Finalized, then ignore this element. The rationale for this is that claim un-finalize reasons can never be updated, their sole purpose is adding when un-finalizing.
The request allows the claim field preprocessingDone and pricingDone to be updated. Setting preprocessingDone to the value true means that the claim will not be sent out for preprocessing. Setting pricingDone to the value true means that the claim will not be sent out for pricing.
The diagnosis element may specify dynamic fields that extend the Claim Diagnoses and Claim Line Diagnoses tables. Ignore duplicate combinations of diagnosis and diagnosis type, as in the Claims In Integration Point.
If the update specifies a messages element, processing depends on the indicator overwriteMessages. If this is set to true (or not specified), all existing messages that originated from either a manual edit or an external source will be removed and replaced with the messages specified in the request. If overwriteMessages is set to false, existing messages will be retained, and add the messages specified in the request to the claim or claim line.
To prevent duplicates, any message specified in the request will only be added to the claim or claim line, if it’s not already present. To determine whether a message is already present (and as such is a duplicate), all attributes of the message (except origin) will be taken into account: that is, code, parameter 0 through 9, transaction source, and reference code. Messages in the request itself are de-duplicated almost in the same manner; all attributes (including origin) will be taken into account.
It is possible to specify the origin of the message (EXTERNAL or MANUAL). If the origin will not be specified, then the message added as a result of using this integration point will be considered to have originated from an external source (origin EXTERNAL). Claims requires knowledge of message origins especially when reprocessing a claim.
Through this integration point claim tag actions can be set. The allowable values are R (Redo), S (Skip), H (Hold), F (Force) and U (Undo). For all actions except Undo, this means a straightforward update of the claim tag action. The claim tag actions that are configured as being possible will be created first through a business rule. The claim tag actions that are sent in are just updates of the existing claim tag actions. If sending in a claim tag action for a skip tag that was not created as a claim tag action, then nothing happens: no claim tag action will be created nor any message will be generated.
Undo mimics the Undo functionality in the MANUAL CHANGE page: it first discards the existing tagged results for that claim and ends by setting the skip tag action to Redo. For example, a skip action of Skip exists for iCes edits and Undo is sent in then the iCes edits tagged results will be removed after which the skip tag action for iCes edits gets the value Redo.
Updating Pends
Update Request
Set the status of the claim to CHANGE. The indicators preprocessingDone and pricingDone are unchecked if they are not explicitly set in the request.
If there are new pend reasons in the request, they are then attached to the claim or claimline in the status CHANGE.
Attaching pend reasons deviates from the standard HTTP behavior of working with a detail list. Here, the system looks at each pend reason sent in the request. Attach the pend reason to the claim or claimline if it is a new one, otherwise it is ignored (when sending an existing one in the request). The pend reason code determines the uniqueness. Also, the existing pend reasons will not be removed when an existing pend reason has not been sent in the list.
Update and Submit
The system first resolves the relevant[2] pends for the current claim (status) only if the user has access privileges to all the relevant pend reasons. Remove the resolved pend reasons from the claim, bill and claim line. If there is a relevant unresolved pend reason for which the current user has no access, make no change to resolve them in the response.
If no relevant pend reasons remain, the system checks for an open workflow task for that claim. If so, the workflow integration point sends out a message to inform the workflow distribution system that the task can be closed. Then set the status of the claim to CHANGE (is not already). The indicators preprocessingDone and pricingDone are unchecked if they are not explicitly set in the request. The system attaches pend reasons that are sent in the request (this is same as described for the update request). The claim is then submitted and it re-enters the level 2: Receive, Enter and Change Claim flow and triggers the exact same process as submitting a claim in the status CHANGE manually (through UI - Change page). That is, if any relevant pend reasons remain (this is possible when new pends are sent in the request), the claim’s status remains CHANGE. If at least one of the remaining relevant pend reasons has a checked publish message indicator, a new workflow integration point message will be sent out. In effect, a claim will not be picked up by the process flow until all the relevant pend reasons have been resolved.
Unlocking Claims Lines
When unlocking a locked claim line using the indicator unlock, updates and delete on the claim line will be allowed. The status of the locked claim line will be cleared.
The system ignores this indicator for an already unlocked line.
Updating Allowed Amount or Allowed Number of Units
When updating the allowed amount and/or the allowed number of units (on a reservation or claim), the new values will normally be no longer in sync with the provider limit consumptions. This happens in a situation where the allowed amount and/or allowed number of units are determined by an external party, but the callouts should be done internally.
This functionality is similar to changing the allowed amount and/or allowed number of units in the Manual Pricing page, but restricted to the effects on the claim line at hand.
Therefore, for each line on which at least one allowed amount and allowed number of units was edited, take the following actions:
-
The keep pricing and manual pricing indicators
-
are checked for a request that is not the result of a callout rule
-
are untouched for a request that is the result of a callout rule
-
-
Uncheck the keep benefits indicator if checked
-
Remove all claim line messages that originated from provider limits (origin PRICING LIMIT)
-
Recalculate the provider limit consumptions of the claim line based on the edited allowed amount and/or allowed number of units:
-
It is possible that existing provider limit consumption has to be updated
-
It is possible that existing provider limit consumption (plus counter period or counter) has to be deleted
-
It is possible that new provider limit consumption (plus counter period or counter) has to be created
-
-
Re-evaluate and create new provider limit category messages and/or reservation regime messages.
The allowed amount element:
<allowedAmount currencyCode >{value} </allowedAmount> ...
It is possible that the currency of an existing allowed amount has been changed. Because this is illogical, it raises a fatal message (CLA-IP-UPDT-042).
Updating Expiration Date
When updating an expiration date on the reservation claim, the expiration date on the provider limit consumptions of all the claim lines that are not locked is updated to the new date.
Updating Price Principal Procedure Indicators
Price principal procedure indicators will typically be set either through Claims In or through the process field derivation rules. It is, however, possible to update one or more of these indicators through either the UI or the Claims Update IP; the functionality of these updates is analogous.
If releaseOverride has value true then the indicator to keep principal procedures is set to false, irrespective of one of the price principal procedures indicators being set or not. This has the effect that the process field derivation rules for the price principal procedure indicators are not skipped.
if releaseOverride is not specified or has value false and one or more price principal procedure indicators are specified in the Claims Update IP then the indicator to keep principal procedures is set to true. This has the effect that the process field derivation rules for the price principal procedure indicators are skipped.
Adding and Removing Claim Lines
A new claim line is created if the claim line code specified in the request does not match with any existing claim line. A value must be provided for all required fields (For example, for field 'Sequence').
To delete claim lines, the element claimline features the indicator deleted. If delete is set to true, the existing claim line (matched on code) is deleted.
Claim Line Replacements
New claim line replacements can be designated by this integration point: For an elaborate description of this functionality, refer to the text on the Claims In integration point (HTTP) (in the implementation guide for claims).
The following specifics with regard to the Claims Update integration point:
-
Replacements can only be designated for claim lines which are not yet replaced. A fatal error message is raised when the request message designates a replacement for a claim line that is already replaced by another line (CLA-IP-UPDT-037).
-
It is not possible to update replaced claim lines (that is, claim lines replaced by other claim lines). Trying to do so will raise a fatal error message (CLA-IP-UPDT-015).
-
It is not possible to delete replaced claim lines (that is, claim lines replaced by other claim lines). Trying to do so will raise a fatal error message (CLA-IP-UPDT-035).
-
It is possible to delete replacement claim lines (that is, claim lines which replace other claim lines). Upon deleting a claim line which is itself the replacement of one or more other claim lines, those claim line replacements are voided. That is, the replaced claim lines are no longer marked as replaced. However, note that a replacement must be voided in its entirety or not at all. If replacing a claim line by multiple other claim lines (that is, an un-bundling) either all replacement lines must be deleted (which would void the replacement), or none of them. Deleting one or more of the replacement lines but not all raises a fatal error message (CLA-IP-UPDT-036).
-
It is not possible to update the serviced entity type of an existing claim (line). Trying to do so will raise a fatal error message (CLA-IP-UPDT-044).
To avoid conflicting situations during processing, apply the following execution order:
-
Execute deletes of replacement claim lines before execution of claim line updates, deletes and (new) claim line replacements. This entails that existing claim line replacements are voided first (where applicable) so that updates, deletes and new claim line replacements can be executed.
-
Execute addition of new claim lines before execution of claim line replacements. This makes it possible to specify claim line replacements both for existing claim lines and for new claim lines.
Response Messages
The following messages can be returned to clarify why an update request failed to execute.
Code | Sev | Message |
---|---|---|
CLA-IP-UPDT-001 |
Fatal |
The claim code {code} is unknown |
CLA-IP-UPDT-002 |
Fatal |
The claim line code {code} is unknown |
CLA-IP-UPDT-003 |
Fatal |
The provider with code {code} ({flexCodeDefinitionCode}) is unknown |
CLA-IP-UPDT-004 |
Fatal |
The diagnosis code {code} ({flexCodeDefinitionCode}) is unknown |
CLA-IP-UPDT-005 |
Fatal |
The procedure code {code} ({flexCodeDefinitionCode}) is unknown |
CLA-IP-UPDT-006 |
Fatal |
The serviced person code {code} is unknown |
CLA-IP-UPDT-007 |
Fatal |
The message code {code} is unknown |
CLA-IP-UPDT-008 |
Fatal |
The data access group code {code} is unknown |
CLA-IP-UPDT-009 |
Fatal |
The specialty code {code} is unknown |
CLA-IP-UPDT-010 |
Fatal |
The coverage regime code {code} is unknown |
CLA-IP-UPDT-011 |
Fatal |
The product code {code} is unknown |
CLA-IP-UPDT-012 |
Fatal |
The pend reason code {code} is unknown |
CLA-IP-UPDT-013 |
Fatal |
The modifier code {code} is unknown |
CLA-IP-UPDT-015 |
Fatal |
The claim line {code} cannot be updated as it is a replaced line |
CLA-IP-UPDT-016 |
Fatal |
Cannot add pend reasons to claim {code} as it has the Entry status |
CLA-IP-UPDT-017 |
Fatal |
Cannot add pend reasons to claim line {code} as its claim has the Entry status |
CLA-IP-UPDT-018 |
Fatal |
The cover withhold category code {code} is unknown |
CLA-IP-UPDT-019 |
Fatal |
The un-finalize reason code {code} is unknown |
CLA-IP-UPDT-020 |
Fatal |
The claim cannot be un-finalized because it is settled |
CLA-IP-UPDT-022 |
Fatal |
The diagnosis type code {typeCode} is unknown |
CLA-IP-UPDT-023 |
Fatal |
The limit code {code} is unknown |
CLA-IP-UPDT-026 |
Fatal |
The location type code {code} in combination with claim form code {code} is unknown |
CLA-IP-UPDT-027 |
Fatal |
The second procedure code {code} ({flexCodeDefinitionCode}) is unknown |
CLA-IP-UPDT-028 |
Fatal |
The third procedure code {code} ({flexCodeDefinitionCode}) is unknown |
CLA-IP-UPDT-030 |
Fatal |
Field {procedure field} is not configured for this claim form |
CLA-IP-UPDT-031 |
Fatal |
The contract reference {code} is unknown |
CLA-IP-UPDT-032 |
Fatal |
The claim line code {code}, specified for (un)bundling purposes, is unknown |
CLA-IP-UPDT-033 |
Fatal |
The claim line replacements are not specified consistently |
CLA-IP-UPDT-034 |
Fatal |
A claim must have at least one claim line |
CLA-IP-UPDT-035 |
Fatal |
Claim line {code} cannot be deleted because it is replaced |
CLA-IP-UPDT-036 |
Fatal |
Replacement claim line(s) {claim line codes separated by ","} cannot be deleted without also deleting co-replacement claim line(s) {claim line codes separated by ","} |
CLA-IP-UPDT-037 |
Fatal |
Claim line {code} cannot be replaced by claim line {code} because it is already replaced by claim line(s) {claim line codes separated by ","} |
CLA-IP-UPDT-038 |
Fatal |
The funding arrangement code {code} is unknown |
CLA-IP-UPDT-039 |
Fatal |
The product line code {code} is unknown |
CLA-IP-UPDT-040 |
Fatal |
The product family code {code} is unknown |
CLA-IP-UPDT-041 |
Fatal |
The skip tag code {code} is unknown |
CLA-IP-UPDT-042 |
Fatal |
The new allowed amount currency should not differ from the existing one |
CLA-IP-UPDT-043 |
Fatal |
The serviced object code {code} and type {code} is unknown |
CLA-IP-UPDT-044 |
Fatal |
The serviced entity type {singular display name} in the request does not match with the serviced entity type {singular display name} on the existing claim |
CLA-IP-UPDT-045 |
Fatal |
Claim {code} with status {status} cannot be updated |
CLA-IP-UPDT-046 |
Fatal |
Claim {code} cannot be updated without specifying an un-finalize reason |
CLA-IP-UPDT-047 |
Fatal |
Only message origins MANUAL,CANCEL or EXTERNAL are allowed |
CLA-HTTP-006 |
Fatal |
The specified authorization regime code {code} is unknown |
CLA-HTTP-007 |
Fatal |
The specified waiting period regime code {code} is unknown |
CLA-HTTP-008 |
Fatal |
The specified post benefits regime code {code} is unknown |
CLA-HTTP-009 |
Fatal |
The specified coverage specification code {code} is unknown |
Attaching a Fatal Message to a Finalized Claim
A payer has a process where a claim goes through a fraud or abuse check. Because this check takes a fair amount of time, and only a relatively small number of claim lines are actually indicative of fraud, the payer chooses not to pend claims in Claims for the duration of this check, but rather to do the check after the claims have been finalized. As a consequence, some claim lines are originally accepted but are denied once the fraud check turns out to be positive.
This process can be automated using the Claims Update Integration Point.
Assume a finalized claim with code "1234" and 4 claim lines with the following data:
- Claim Lines
Code | Procedure | Start Date | Messages |
---|---|---|---|
1 |
99218 |
January 03, 2020 |
|
2 |
99761 |
January 03, 2020 |
|
3 |
88880 |
January 03, 2020 |
|
4 |
99900 |
January 03, 2020 |
The following pend reason is configured:
- Pend reason
Code | Description | Publish message? |
---|---|---|
PICAU |
Pend in change for an automatic update |
No |
The following message is configured:
Message
Code | Message |
---|---|
FRAUD |
Line is denied for suspect fraud |
When using the Claims Update Integration Point , it is called with the following message
<claims> <claim code="1234"> <claimUnfinalizeReasonList> <claimUnfinalizedReason code="Unfinalized for automatic update" sourceReference="AUTOUPD"/> </claimUnfinalizeReasonList> <claimPendReasonList> <claimPendReason code="PICAU" sourceReference="AUTOUPD"/> </claimPendReasonList> <claimLineList> <claimLine code="3"> <claimLineMessageList> <claimLineMessage code="FRAUD"/> </claimLineMessageList> </claimLine> </claimLineList> </claim> </claims>
This will cause claim 1234 to be un-finalized and pended in the status Change.
Because the pend reason PICAU has a publish message indicator NO
, no workflow event is published.
This request will take also update claim line 3 of claim 1234
by attaching the FRAUD message.