Submit a Large Claim For Processing

A claim is identified as a large claim when its Process Category is set to Large Claim.

If the Process Category has no value, then the claim is classified as a Regular Claim, and the submit operation works as explained in Submit a Claim For Processing.

Design Principle

  • Once a claim is identified as a Large Claim, the submit operation is available only at the Large Claim level.

    • A sub-claim cannot be submitted directly.

  • The submit operation on the large claim has the following options:

    • Submit all the linked sub-claims.

    • Select one or more sub-claims and submit them for processing.

Resource Representation

Not all large claims are eligible for processing; for example, claims with the status Finalized are not eligible. Whether a large claim can be processed or not is derived by the presence or absence of the Submit link.

Resource Representation of a Claim that can be Submitted:
{
  ... claim properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/largeclaimsubmit",
      "rel": "claim:submit",
      "httpMethod": "POST"
    }
  ]
}

Payload

The following payload can be passed to select the list of sub-claims to be submitted. If no payload is passed, then all the sub-claims are selected to submit.

{
    "claimUnfinalizeReasonList": [
                {
                    "sourceReference": "<source reference value>",
                    "unfinalizeReason": {
                        "id": "<id of unfinalize reason>"
                    },
                    Extensibility data
                }
    ],
    "subClaimList": [
        {
            "code": "" // code of the sub claim
        },
        {
            "code": ""
        },
        {
            "code": ""
        }
    ]
}

Based on the aforementioned payload, all or the selected sub-claims are submitted for processing when a large claim is submitted. See Large Claims Flow for more details about large claims processing.

The submit link does not exist from the resource representation of a claim that cannot be submitted, which means the submit link is not available for a large claim in the status Finalized.

Resource Representation of a Claim that Cannot be Submitted:
{
  ... claim properties ...
  "links": [
    {
    "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
    "rel": "self"
    }
  ]
}
It is strongly recommended that clients use the presence of the link to determine whether a claim can be submitted or not. Clients should not hard code assumptions about claims being submittable. Clients that do make those assumptions may break when Oracle Health Insurance changes the implementation.

A large claim always includes a status link, unlike a regular claim or a sub-claim.

{
  ... claim properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/status",
      "rel": "claim:status"
    }
  ]
}
Table 1. Submit Link for a Large Claim for Processing
Status of Large Claim Link to Submit Link Status Resource Available

Entry

Yes

Yes

In Process

Yes

Yes

Manual Adjudication

Yes

Yes

Finalize

No

Yes
Table 2. Submit Eligibility for a Sub-Claim for Processing
Status of the Claim Eligible for Submit

Adjudication done

No

Benefits done

No

Change

Yes

Entry

Yes

Finalized

No

Initial

No

Manual adjudication

Yes

Manual benefits

Yes

Manual pricing

Yes

Manual pricing adjudication

Yes

Pricing adjudication done

No

Pricing done

No

Pricing finalized

No

Sent out for preprocessing

No

Sent out for pricing

No

Submit Process

By performing a POST operation on the following endpoint:

http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/largeclaimsubmit

  • The submit process gets triggered for the large claim.

  • The system expects for unfinalize reason if at least one of the sub-claim is in finalized status.

  • See Large Claims Flow for more details on process flow.

At the time of submit, if a change log is present, then the system will ignore the sub-claim list in the request. The presence of a change log may result in an update of all the sub-claims, and therefore, all the sub-claims may be re-processed.

Response

See the "Response Messages" section in the HTTP API/IP Concepts in the Developer Guide 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/{id}/status

This enables the external system to track the progress by issuing a GET to the status URI returned in the Location header. See the section "HTTP API Operations" in the HTTP API chapter in the Developer Guide for more details on the status resource.

API Conversation and Interaction

Use Case 1: Claim Can be Submitted

The claim is in a status where it can freely be submitted.

This use case is represented graphically at a high level by the following diagram.

http api long operation poll.drawio

Let us explore each of the components shown in the diagram:

  1. It shows an initial stage of a claim resource that is returned from some prior interaction at 0.

  2. The server has embedded the link relation for claim:submit, with which an API consumer can interact with at 1.

  3. The server acknowledges this submission with a HTTP 201 (created) message and sets an HTTP location header to the Status resource at 2.

  4. The status resource can subsequently be refreshed (i.e., polled for) by an API consumer to track progress at 3. A consumer can interrogate the status resource’s mandatory completed attribute to determine whether it is (still) useful to refresh the Status resource.

  5. Note that the status resource will have a link relation of rel="related" to identify the related resource that was affected by a completed process - see 4.

  6. In case of processing errors. i.e., progress attribute failed - the status resource contains an error property, which provides the detail of the issue(s).

Interaction Example Messages

The client requests a claim, and the claim is returned as follows:

{
  ... claim properties ...
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/largeclaimsubmit",
      "rel": "claim:submit"
      "httpMethod": "POST"
    }
  ]
}

The client submits the claim by initiating a following POST request:

http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/largeclaimsubmit

The claim processing is started, and the server responds with status 201. A link to the status resource is returned in the Location header as follows:

Location: http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/status

The clients can now track the progress by issuing a GET to the status URI returned in the Location header.

  • While the claim is being processed, the status resource will be returned as follows:

Processing - When one or more sub-claim submit process is in-progress
{
  "progress": "processing",
  "completed": false,
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/status",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
      "rel": "related"
    }
  ]
}

  • When the processing ends successfully with no errors, the status resource returns as follows:

Succeeded - When all the sub-claims submit process is successfully completed
{
  "progress": "succeeded",
  "completed": true,
  "links": [
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/status",
      "rel": "self"
    },
    {
      "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
      "rel": "related"
    }
  ]
}

  • When the processing ends unsuccessfully, the status resource returns as follows:

Failed - Due to an error at the large claim or at the sub-claim level
{
    "progress": "failed",
    "completed": false,
    "links": [
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/claims/{id}/status",
            "rel": "self"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claims/{id}",
            "rel": "related"
        },
        {
            "href": "http://[hostName]:[portNumber]/[api-context-root]/generic/claimactivities/{id}",
            "rel": "operator"
        }
    ]
}

Performing a GET on the activity link, user will be able to see all the details related to failure and the related activity messages.

Restarting the activity re-processes the failed activities and the respective sub-claims automatically.

Status Resource

If the status resource is requested standalone, that is, when the claim is not yet submitted and is in a submittable state, the response is as follows:

{
  "progress": "notStarted",
  "status": "{Current Status of the Claim}"
}

Pend Resolution

If the claim has any unresolved or existing pend reasons at the large claim level, then the claim is not submitted. Status code 409 is returned with the message CLA-CLAI-035.

Use Case 2.1: Claim Cannot be Submitted, there is Status Information

The claim resource representation will not include a submit link in this situation. However, clients may still send a payload against the submit URI (the client may hold a stale one or construct the link themselves). When a client does send a submit request, HTTP status code 409 is returned, and the claim is not submitted.

The claim will include a status link that can be used to get the status information and restart the failed task(s).

Only tasks with the status Errored can be restarted. When trying to start a task with another status, HTTP status code 409 is returned with an error message OHI-TASK-IP-001: Only tasks in status Error can be processed.

Use Case 2.2: Claim Cannot be Submitted as the Sub-Claim is in Error Status

The large claim is in In-Process status, the request includes sub-claims, and at least one sub-claim has an error.

In this scenario, the submit process reprocesses all the error tasks automatically i.e, the sub-claim(s) processing errors are reprocessed by the system.

See Large Claims Flow for more details.

Authorization

A user authorization configuration protects access to this feature. The relevant access restriction is largeclaims.submit IP.

In addition to the above access check, the system also checks for the Claim Approval Limit data access check when a claim in the status Manual Adjudication is submitted for processing.

If the user does not have access based on approval limit, 403 is returned by the system along with the message Total covered amount exceeds your authorized limit. You cannot process this claim.

Response Messages

Success

HTTP 201 - Returns after the operation is completed successfully.

Failure

Table 3. Failure
Response Severity Description

CLA-IP-SUBLC-001

Fatal

This integration point is not supported for a claim with a process category Null or SubClaim

CLA-IP-SUBLC-002

Fatal

The claim code {code} is unknown

CLA-IP-SUBLC-003

Fatal

The unfinalize reason id/code {id/code} is unknown

CLA-IP-SUBLC-004

Fatal

The unfinalize reason code is required as one or more claims with process category sub-claim is in finalized status

CLA-IP-SUBLC-005

Fatal

One or more claims with process category either large claim or sub-claim is not in a status that allows submit

See the Response Messages section in the HTTP API Integration Points for more details.