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>

Dynamic Fields and Records

For details on how external interfaces can provide values for dynamic fields and dynamic records in request messages and how they are handled by the Oracle Health Insurance application, refer to the concepts in the Developer Guide.

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.

Table 1. Response Messages
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

Use Cases

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:

Table 2. Claim Lines
Code	Procedure	Start Date
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:

Table 3. Pend Reason
Code	Description	Publish message?
PICAU	Pend in change for an automatic update	No

The following message is configured:

Table 4. 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.

1. see "Adding and removing claim lines" section

2. Relevant pend reasons - For a claim in the status other than Manual Adjudication or Manual Pricing Adjudication with external benefits, all the unresolved pend reasons with the indicator Adjudication only set to false are considered as relevant. For the status Manual Adjudication and Manual Pricing Adjudication, all the unresolved pend reasons are considered relevant.