Authorizations

The Authorizations Integration Point enables the handling of authorizations and their details in Oracle Health Insurance Authorizations.

Operations

This specific API supports the following operations:

PUT	/authorizations creates or updates an authorization.
PUT	/authorizations/submit creates or updates an authorization and submits it for processing.
GET	/authorizations/{id} retrieves an authorization by its id.
POST	/authorizations/{id}/submit submits an earlier created or updated authorization for processing.
POST	/authorizations/{id}/deny denies a pended authorization.
POST	/authorizations/{id}/tochange brings a pended authorization back into the change status.
POST	/authorizations/{id}/unfinalize brings an approved or denied authorization back into the change status.
GET	/authorizations/{id}/status fetches the current processing state of an particular authorization.
GET	/authorizations/{code}/attachedData fetches attached data for the authorization.
PUT	/authorizations/{code}/attachedData creates or updates attached data on the authorization.

Oracle Health Insurance supports a generic authorizations API and a specific authorizations API.

In addition to the standard generic API operations, the /generic/authorizations API supports the following operations:

GET	/generic/authorizations/key/{key} retrieves an authorization by its authorization code.
PATCH	/generic/authorizations/key/{key} updates an authorization by its authorization code.

Rules

Create or Update Behavior

The authorization code drives whether an authorization is created or an existing authorization is updated.

• If the authorization code in the request does not exist in the system then a new authorization with the provided authorization code is added to the system.

• If the authorization code in the request exists in the system then the authorization details are updated as per the data provided in the request.

• If the authorization code in the request is empty, the system considers the request a new authorization. The system generates a unique authorization code using the dynamic logic function with the signature 'Authorization Code Generation'. If no dynamic logic function with the signature 'Authorization Code Generation' exists, the system assigns the authorization id to authorization Code.

Setting the Status

The integration point does not offer the possibility to set the status of the authorization. A new authorization is by default created with the status Entry.

Whenever a new authorization is created or when the status of an authorization is changed, the system creates an authorization status history record.

• If the request updates an authorization with the status Entry or Change, it does not change the status and it does not add an authorization status history record. No authorization status history is added.

• If the request updates an authorization with the status Approved or Denied, the system creates a new version with status Change. The request must contain an unfinalize reason. If the request does not contain an unfinalize reason then the system raises a fatal error and adds message AUT-IP-AUTI-015 to the authorization.

• If the request updates an authorization with the status Change or Pended then the system removes all authorization pend reasons from the authorization. The system does not resolve the authorization pend reason, that is, the system does not update the authorization pend history records.
  If a pend notification was sent out when the authorization pended, then the system also sends out a 'Pend Done' notification through Outbound Restful Service Invocation to the external system for the removed pends.
  If the request updates an authorization with the status Pended, then the system sets the status to Change.

• If the request updates an authorization with the status In Process that has stopped with technical errors then the system sets its status to Change. The system removes any existing technical error tasks for this authorization.

Attribute Handling

The system handles updates on an authorization as follows:

• The system discards attributes that are not provided in the request.

• The system overwrites the existing values with the values provided in the request.
  The system overwrites existing values for an attribute with an empty value if the request holds an empty value for that attribute.

• When updating a detail that is effectively part of a list of values, all values in the list have to be present.
  

  Example

  The original authorization is for procedures A, B and C (specified on three different authorization lines). If the goal is to remove the authorization line for procedure C from the list of authorization lines, then the update request should contain an authorization with two authorization lines, one for procedure A and one for procedure B).

Authorization Type

The authorization Type must be either 'A' (Authorization), 'N' (Notification), or 'R' (Referral).

Requester

The requester is the person or organization or provider requesting the authorization for services. Therefore only the requesterRelationCode or the <requesterProvider> element can exist.

The requester reference is the number or code used by the requester to identify the authorization.

Insurable Entity

The insurable entity type must exist as a supported insurable entity type for the insurance type of the authorization form (authorizationFormCode) in the request (AUT-IP-AUTI-019).

If the insurable entity type is 'Person' then the insurable entity code must be an existing (relation of type) Person. If the insurable entity type is an object then the insurable entity code must be an existing object of that insurable object type (AUT-IP-AUTI-008).

Unfinalize Reason

The system overwrites existing unfinalize reasons of the authorization if an authorization is finalized and unfinalized again. No history is kept of unfinalize reasons.

The system only allows adding an unfinalize reason for authorizations with status Approved or Denied. When the request holds an unfinalize reason for an authorization in another status then the system ignores the unfinalize reason. The system does not raise a message for this situation.

Messages

The system allows adding non system specific messages through the request. If the request holds a system specific message then the system raises a fatal error and adds message AUT-IP-AUTI-014.

The indProcessing of the authorization message is by default set to No.

Whenever a request updates an authorization, the system removes all existing authorization messages and adds the ones in the request. As a consequence, authorization messages that were added by the system during a previous processing (authorization message with indicator processing set to Yes) will always be removed from the authorization.

Each {message} element may contain up to 10 values: attributes "value0" through "value9". The system uses these values to populate the respective placeholders in the message text. In the event that no place holder exists for the specified value, the system ignores the value. In the event that no value is specified for a place holder, that placeholder remains empty.

Currency

If the request specifies a currency code, that denotes that all amount fields (when specified) are in that currency. If the request does not specify a currency code and one or more amount fields are sent in, then the system uses the default currency. This way, it’s only necessary to send in a currency code when deviating from the default.

The currency field for requested amount cannot be updated through this API.

Authorization Line Code

If the authorization line code in the request is left blank, the system generates a code using the Authorization Line Code Generation dynamic logic function or using the sequence of the line within the authorization if the code generation function is not configured.

Immediate Submit

The PUT /authorizations/submit operation submits the authorization for processing immediately after completing the create or update. The create or update must be completed including all steps like the setting of the status, creating status history records and, if applicable, removing pend reasons, sending out 'Pend Done' notifications or adding unfinalize reasons before submitting the authorization for processing. If the create or update of an existing authorization was not successful the authorization will not be submitted for processing. See Submit Authorization for a detailed description of submitting an authorization for processing.

Request Message

The system accepts the /authorization and /authorization/submit request message in the following format:

Authorization Request Message (click to open)

{
    "code": "",
    "authorizationType": "",
    "formCode": "",
    "brandCode": "",
    "requesterRelationCode": "",
    "providerGroupScope": "",
    "serviceSpecialtyCode": "",
    "requesterAuthorizationReference": "",
    "currencyCode": "",
    "startDate": "",
    "endDate": "",
    "requestedRenewalReference": "",
    "requestedRenewalPeriodLength": ,
    "requestedRenewalPeriodUnitOfMeasure": "",
    "renewalReference": "",
    "renewalPeriodLength": ,
    "renewalPeriodUnitOfMeasure": "",
    "requestedNumberOfUnits": ,
    "requestedServiceDays": ,
    "authorizedNumberOfUnits": ,
    "authorizedServiceDays": ,
    "indOverrideCoverLimits": ,
    "internalRemarks": "",
    "dataAccessGroupCode": "",
    "unfinalizeReasonCode": "",
    "requestedAmount": {
        "currency": "",
        "value":
    },
    "authorizedAmount": {
        "currency": "",
        "value":
    },
    "requesterProvider": {
        "flexCodeDefinitionCode": "",
        "code": ""
	},
    "serviceProvider": {
        "flexCodeDefinitionCode": "",
        "code": ""
	},
    "locationProvider": {
        "flexCodeDefinitionCode": "",
        "code": ""
    },
    "authorizationBasketList": [
        {
            "code": "",
            "startDate": "",
            "endDate": ""
		}
    ],
    "authorizationServiceTypeList": [
        {
            "code": ""
		}
	],
    "authorizationDiagnosisList": [
    ...
	],
	"authorizationMessageList": [
    ...
	],
    "authorizationLineList": [
        {
            "code": "",
            "endDate": "",
            "requestedRenewalPeriodUnitOfMeasure": "",
            "renewalPeriodLength": ,
            "requestedRenewalReference": "",
            "renewalPeriodUnitOfMeasure": "",
            "authorizedServiceDays": ,
            "requestedServiceDays": ,
            "requestedRenewalPeriodLength": ,
            "requestedNumberOfUnits": ,
            "authorizedNumberOfUnits": ,
            "renewalReference": "",
            "startDate": "",
            "procedureGroupCode": "",
            "authorizedAmount": {
                "currency": "",
                "value":
            },
            "requestedAmount": {
                "currency": "",
                "value":
            }
        }
	],
	"authorizationMessageList": [
		{	code=""
      indInherit=""
      value0=""
      value1=""
      value2=""
      value3=""
      value4=""
      value5=""
      value6=""
      value7=""
      value8=""
      value9=""
		}
	]
}

Start Date and End Date

The start date and the end date specify the period wherein the authorization is valid.

Data Access Group Code

The data access group restricts the access to this authorization. See Data Access Restriction for more details.

Override Cover Limits?

Should the adjudication cover stop limits be overridden if this authorization is applied in Claims?

Authorization

This API requires a grant for access restriction Authorization In IP.

Response Messages

The Oracle Health Insurance application creates the response messages in response to request messages it receives from external interfaces. Please refer to the "Response Messages" section in the HTTP API/IP Concepts as part of the Developer Guide for more details.

Batches

This Integration Point does not support the handling of multiple requests ('File Based Import') in one go.

Error Messages

The following error messages that are specific to the authorization interface may be returned in the response messages:

Table 1. Error Messages

Code	Severity	Message
AUT-IP-AUTI-001	Fatal	Authorization form code {code} is unknown
AUT-IP-AUTI-002	Fatal	Brand code {code} is unknown
AUT-IP-AUTI-003	Fatal	Service specialty code {code} is unknown
AUT-IP-AUTI-004	Fatal	Requester relation code {code} is unknown
AUT-IP-AUTI-005	Fatal	Requester provider with code {code} and flex code definition {code} is unknown
AUT-IP-AUTI-006	Fatal	Service provider with code {code} and flex code definition {code} is unknown
AUT-IP-AUTI-007	Fatal	Location provider with code {code} and flx code definition {code} is unknown
AUT-IP-AUTI-008	Fatal	Insurable entity {usageName} with code {code} is unknown
AUT-IP-AUTI-009	Fatal	Service type code {code} is unknown
AUT-IP-AUTI-010	Fatal	Procedure with code {code} and flex code definition {code} is unknown
AUT-IP-AUTI-011	Fatal	Diagnosis with code {code} and flex code definition {code} is unknown
AUT-IP-AUTI-012	Fatal	Unfinalize reason code {code} is unknown
AUT-IP-AUTI-013	Fatal	Message code {code} is unknown
AUT-IP-AUTI-014	Fatal	Only non system specific messages can be linked to an authorization
AUT-IP-AUTI-015	Fatal	An unfinalize reason is required when updating an authorization with status 'APPROVED' or 'DENIED'
AUT-IP-AUTI-016	Fatal	Data access group code {code} is unknown
AUT-IP-AUTI-017	Fatal	Currency code is unknown
AUT-IP-AUTI-019	Fatal	The insurable entity type {code} must exist as a supported insurable entity type for the insurance type {code} of the authorization {code}
AUT-IP-AUTI-022	Fatal	Procedure group code {code} is unknown
AUT-IP-AUTI-023	Fatal	Basket code {code} is unknown
AUT-IP-AUTI-024	Fatal	Authorizations in status {status} cannot be Denied
AUT-IP-AUTI-025	Fatal	Authorizations cannot be brought back to Change status from status {status}
AUT-IP-AUTI-026	Fatal	Authorizations in status {status} cannot be Unfinalized

In addition, functional business rule messages may be returned as well as the standard messages related to dynamic fields and records (refer to the "Response Messages" section in the HTTP API/IP Concepts part of the Developer Guide).