Submit a Claim For Processing

Once a claim is stored in Oracle Insurance Claims Adjudication for Health, it can be processed. HTTP API supports the starting of the claims processing with the operation "Submit a Claim for Processing".

For details about the claims processing see the Claims Flow Guide.

Not all claims are eligible for being processed, for example claims in the status 'Finalized' are not. Whether a claim can be processed or not, can be derived by the presence or absence of the "submit" link.

Resource representation of a claim that can be submitted:

{
  ... claim properties ...
  "links": [
    {
      "href": "http://<host>:<port>/api/generic/claims/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/claims//submit",
      "rel": "claim:submit",
      "httpMethod": "POST"
    }
  ]
}

In the resource representation of a claim that can’t be submitted, the submit link is missing:

{
  ... claim properties ...
  "links": [
    {
    "href": "http://<host>:<port>/api/generic/claims/",
    "rel": "self"
    },
  ]
}

It is strongly recommended for clients to use the presence of the link for determining 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 OHI changes the implementation.

Actually, with regards to submitting a claim, three use cases can be distinguished:

Use Case 1: The claim is in a status where manual changes are possible. Submitting the claim will bring it to the next status. Example: claims in status 'Change'.
Use Case 2: The claim is being processed right now, or the last processing has resulted in an error. Submitting the claim is not possible. There is an additional link to the "status" resource which clients can use to monitor the processing or analyze the last error.
Use Case 3: The claim has reached a valid end status. Submitting the claim is not possible. Example: claims in status 'Finalize' or 'Sent out for preprocessing'. In that case, the error "CLA-IP-CLAI-024 : Claims in status {0} cannot be submitted" is returned.

The table below gives an overview:

Status of the claim	Eligible for Submit	Link Status Resource Available
Adjudication done	No	Yes
Benefits done	No	Yes
Change	Yes	No
Entry	Yes	No
Finalized	No	Yes
Initial	No	Yes
Manual adjudication	Yes	No
Manual benefits	Yes	No
Manual pricing	Yes	No
Manual pricing adjudication	Yes	No
Pricing adjudication done	No	Yes
Pricing done	No	Yes
Pricing finalized	No	Yes
Sent out for preprocessing	No	Yes
Sent out for pricing	No	Yes

Status of the claim

Eligible for Submit

Link Status Resource Available

Adjudication done

Yes

Benefits done

Yes

Change

Yes

Entry

Yes

Finalized

Yes

Initial

Yes

Manual adjudication

Yes

Manual benefits

Yes

Manual pricing

Yes

Manual pricing adjudication

Yes

Pricing adjudication done

Yes

Pricing done

Yes

Pricing finalized

Yes

Sent out for preprocessing

Yes

Sent out for pricing

Yes

When a claim is currently being processed, or the last processing did not end in a valid end status, a status link is included:

{
  ... claim properties ...
  "links": [
    {
      "href": "http://<host>:<port>/api/generic/claims/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/claims//status",
      "rel": "claim:status"
    }
  ]
}

Non-blocking

The processing of a claim can take long, because communication with external systems and/or manual intervention may be needed. Because of the possible long time, submitting a claim is an asynchronous operation: the client of this API will become detached from the actual background process. The client can use the "status" resource to monitor that background process. So the client of the API is not blocked, but rather is provided with the means to track progress in an asynchronous fashion.

When this process completes this means that either the claim has been processed or that there were errors during processing. Both of these outcomes are made available/accessible for the consumer of this API.

Concurrent Use

The "submit" link is included in the claims resource representation when a claim is eligible for submit. It is possible that two (or more) clients have a resource representation of the same claim. It may however not be desirable that both clients submit the same claim without noticing. This can be prevented by including the current object version number in the POST payload. For more details, see Operations Overview and Concepts.

If clients omit the object version number from the POST payload, no object version number check takes place.

Resources used in this API

Claim resource

This is a singular resource representing a claim. For more details about the representation, see Default Resource Representation (GET). The claim resource contains the "submit" link or the link to the "status" resource.

Status resource

These resources provide the basic elements with which submitting a claim for processing can be fulfilled - including tracking progress and the ability to show processing errors. As these are individual states of the application, various link relations are defined to allow a consumer to have a conversation with the system.

Link relations used in this API

A link relation is a descriptive attribute attached to a hyperlink in order to define the relationship between the source and destination resources. In the case of submitting a claim for processing, the following link relations are defined.

These link relations are described in the form of Compact URIs (CURIE) references, if no suitable standard link relation exists.

rel="claim:submit"

To eventually have a claim - in the context of this link relation - processed by the system.

rel="claim:status"

To request the status of the current or last claims submit action.

rel="task:process"

To restart the processing of a failed task.

rel="self"

Link to the current resource. This for instance can be used on the status resource to periodically poll the resource for progress tracking.

rel="related"

This is a standard link relation to the related (claim) resource. This should be provided once the request is completed successfully.

API Conversation & interaction

The conversational and interaction style of this API is based on its asynchronous nature. As said above, there are three different use cases. Two out of three support some operation to be triggered. In the third use case, the claim is in valid end status, no operation can be triggered. Those use cases are described in the next sections.

Use Case 1: Claim can be submitted

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

From a high level this use case can be visualized by the following diagram.

Let’s go over the various elements in this diagram:

This shows an initial stage of a Claim resource that was returned from some prior interaction at 0.
The server has embedded the link relation for claim:submit, with which a consumer of the API can interact with at 1.
The server acknowledges this submission with a HTTP 201 (Created) message and sets a HTTP Location header to the Status resource at 2.
The Status resource can subsequently be refreshed (i.e. polled for) to track progress at 3 by a consumer of the API. A consumer can interrogate the Status resource’s mandatory "completed" attribute to find out whether it is (still) useful to refresh the Status resource.
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.
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. The claim is returned like this:

{
  ... claim properties ...
  "links": [
    {
      "href": "http://<host>:<port>/api/generic/claims/",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/claims//submit",
      "rel": "claim:submit"
      "httpMethod": "POST"
    }
  ]
}

The client submits the claim by calling POST on "http://<host>:<port>/api/claims//submit". The claim processing is started, and the server responds with status 202. A link to the status resource is returned in the Location header like this:

Location: http://<host>:<port>/api/claims//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 like this:

{
  "progress": "processing",
  "completed": false,
  "links": [
    {
      "href": "http://<host>:<port>/api/claims//status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/generic/claims/",
      "rel": "related"
    }
  ]
}

When the processing ends successfully (no errors), the status resource will return:

{
  "progress": "succeeded",
  "completed": true,
  "links": [
    {
      "href": "http://<host>:<port>/api/claims//status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/generic/claims/",
      "rel": "related"
    }
  ]
}

When the processing ends unsuccessfully, the status resource returns:

{
  "progress": "failed",
  "completed": false,
  "claimErrorDetails": [
    {
      "detail": "<detailed error message 1>",
      "instance": "http://<host>:<port>/api/generic/tasks/"
      "links": [
        {
          "href": "http://<host>:<port>/api/tasks//process",
          "rel": "task:process"
        }
      ]
    },
    {
      "detail": "<detailed error message 2>",
      "instance": "http://<host>:<port>/api/generic/tasks/",
      "links": [
        {
          "href": "http://<host>:<port>/api/tasks//process",
          "rel": "task:process"
        }
      ]
    },
  ],
 "links": [
    {
      "href": "http://<host>:<port>/api/claims//status",
      "rel": "self"
    },
    {
      "href": "http://<host>:<port>/api/generic/claims/",
      "rel": "related"
    }
  ]
}

The "detailed error message" property shows the details of the technical error, indentical to the "Details" field in in the View Technical Errors page.

Status Resource

If the status resource is asked standalone, that is when the claim in not yet submitted and is in a submittable state, the response will be as under:

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

Pend Resolution

There may be existing pend reasons. Before a claim is submitted, those are resolved automatically. The following applies:

If the claim has any relevant* unresolved pend reasons then the claim is not submitted. Status code 409 is returned with message CLA-CLAI-035.
Otherwise
- all the relevant pend reasons that are resolved are removed.
- all non-relevant unresolved pend reasons are ignored and remain untouched
- if there is an open work flow task for the claim, then the work flow integration point sends out a message to inform the work flow distribution system that the task can be closed
- the claim is submitted for further processing

*further clarification of when a pend reason is relevant:

For claims in the status: change, manual pricing, manual benefits or manual pricing adjudication
- Any pend reason with indicator 'Adjudication Only' set to false
For claims in the status: manual adjudication
- Any pend reason

Use Case 2: Claim cannot be submitted, there is status information

The claim resource representation will not include a "submit" link in this situation. Clients may however still send a payload against the submit URI (the client may hold a stale one, or construct the link themselves). When 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 in status 'Errored' can be restarted. When trying to start a task with another status, HTTP status code 409 is returned with error message OHI-TASK-IP-001: Only tasks in status Errored can be processed.

Authorization

This operation is protected by access restriction "claims.submit IP". A grant to this access restriction is necessary to make a request. Upon receiving a request, the system checks for finer access controls based on the claims status. If the user does not have access to submit a claim in a particular status; then 403 is returned by the system.

These access restrictions are as specified below:

Access Restriction	Description
claims.allstatus.submit IP	User can submit a claim in any status
claims.entry.submit IP	User can submit a claim in status 'entry'
claims.change.submit IP	User can submit a claim in status 'change'
claims.manualpricing.submit IP	User can submit a claim in status 'manual pricing'
claims.manualpricingadjudication.submit IP	User can submit a claim in status 'manual pricing adjudication'
claims.manualbenefits.submit IP	User can submit a claim in status 'manual benefits'
claims.manualadjudication.submit IP	User can submit a claim in status 'manual adjudication'

Access Restriction

Description

claims.allstatus.submit IP

User can submit a claim in any status

claims.entry.submit IP

User can submit a claim in status 'entry'

claims.change.submit IP

User can submit a claim in status 'change'

claims.manualpricing.submit IP

User can submit a claim in status 'manual pricing'

claims.manualpricingadjudication.submit IP

User can submit a claim in status 'manual pricing adjudication'

claims.manualbenefits.submit IP

User can submit a claim in status 'manual benefits'

claims.manualadjudication.submit IP

User can submit a claim in status 'manual adjudication'