Persons Integration Point

When members' details of members are primarily maintained outside Oracle Health Insurance, Oracle Health Insurance needs an up-to-date copy of these details. The Person Integration Point enables external parties to create and maintain these copies.

Operations

This specific API supports the following operations

PUT

/persons creates or updates a person.

GET

/persons/{id} retrieves a person by its id.

In addition to the standard generic API operations, the generic persons API supports the GET and the PATCH operations on /generic/persons/key/{key}. This enables retrieving and updating a person based on its code (the {\key}).

To exclude the person covered services from the response, add the following header property with the URI:

header - excludeCoveredServices: true

Rules

Uniqueness

A person’s code is unique to the application’s persons, organizations, and banks. A person’s identifier of a unique identifier type is unique to the application’s persons, organizations, and banks.

Create or Update Behavior

In combination with the identifier type, the person code drives whether the API creates a new person or updates an existing person.

If the identifier type in the request is empty and the person code in the request matches the person code of an existing person, Oracle Health Insurance considers the details to be an update to that existing person.
If the combination of the identifier type and the person code in the request match the identifier type and value of an existing person, Oracle Health Insurance considers the details to be an update to that existing person.
If the identifier type in the request is empty and the person code in the request does not match the person code of an exiting person, Oracle Health Insurance adds a new person with the provided person code and details.

If the combination of the identifier type and the person code in the request does not match the identifier type and value of an existing person, Oracle Health Insurance adds a new person with a generated person code^[1]
If the person code in the request is empty, Oracle Health Insurance adds a new person with a generated person code^[1].

Oracle Health Insurance enforces person codes to be unique across all relations, regardless of the source of the relation. However, identifier types can be non-unique. Suppose the combination of the identifier type and the person code in the request matches multiple persons, In that case, the application returns error message REL-IP-RELA-027: "Multiple relations matched on identifier {identifier}" and does not update or create any person.

Request Messages

Each request message can contain the details of one person.

The details of what information needs to be in a given request message vary based on factors such as whether details have been sent before and the category of details that have been added or updated.
For details on how values in the request messages are handled, see Property Representation and Handling (PUT, POST, PATCH) for more information..

Person

The system accepts the person’s request message in the following format:

Person Request Message (click to open)

<person
  code=""
  identifierTypeCode=""
  name=""
  initials=""
  firstName=""
  gender=""
  genderIdentificationCode=""
  prefixCode=""
  suffix=""
  middleName=""
  nameFormatCode=""
  dateOfBirth=""
  dobInterpretation=""
  namePartner=""
  partnerPrefixCode=""
  phoneNumberBusiness=""
  phoneNumberMobile=""
  phoneNumberPrivate=""
  emailAddress1=""
  emailAddress2=""
  faxNumber=""
  outputLanguageCode=""
  preferredLanguageCode=""
  endDate=""
  accessRestrictionCode=""
  contactDetailsAccessRestrictionCode=""
>
  <relationIdentifierList>
    <relationIdentifier
      identifierTypeCode=""
      identifier=""
      enabled=""     />
  </relationIdentifierList>
  <relationLinkList>
    <relationLink
      relationLinkTypeCode=""
      direction=""
      relationCode=""
      enabled=""
    />
  </relationLinkList>
  <maritalStatusList>
    <maritalStatus
      maritalStatusTypeCode=""
      startDate=""
      endDate=""
    />
  </maritalStatusList>
  <personTitleList>
    <personTitle
      titleCode=""
    />
  </personTitleList>
  <addressList>
    <address
      addressTypeCode=""
      street=""
      houseNumber=""
      numberAddition=""
      additionalPart1=""
      additionalPart2=""
      additionalPart3=""
      city=""
      county=""
      stateAndCountyCode=""
      postalCode=""
      countryRegionCode=""
      countryCode=""
      startDate=""
      endDate=""
      accessRestrictionCode=""
    />
  </addressList>
  <bankAccounts>
    <bankAccount
      bankAccountNumber=""
      bankAccountNumberDebit=""
      bankCode=""
      bankAccountValidationCode=""
      specialName=""
      indPreferred=""
      startDate=""
      endDate=""
    />
  </bankAccounts>
  <relationTagList>
    <relationTag
      tagTypeCode=""
      startDate=""
      endDate=""
    />
  </relationTagList>
  <assignedProviderList>
    <assignedProvider
      providerAssignmentTypeCode=""
      startDate=""
      endDate=""
    >
      <provider
        code=""
        flexCodeDefinitionCode=""
     />
    </assignedProvider>
  </assignedProviderList>
  <personCoveredServiceList>
    <personCoveredService
      productCode=""
      serviceOptionServiceCode=""
      coveredServiceTierCode=""
      coveredServiceType=""
      score=""
      startDate=""
      endDate=""
      waitStartDate=""
      indWaiver=""
      waiverReason=""
    />
  </personCoveredServiceList>
  <contractAlignmentList>
    <contractAlignment
      capitationContractCode=""
      startDate=""
      endDate=""
    />
  </contractAlignmentList>
  <relationLobAccessRestrictionList>
    <relationLobAccessRestriction
      accessRestrictionCode=""
    />
  </relationLobAccessRestrictionList>
</person>

Authorization

A user authorization configuration protects access to this feature. The relevant access restriction is Person In IP.

Response Messages

The Oracle Health Insurance application creates the response messages in response to request messages it receives from external interfaces. See Response Messages for more details.

Batches

Oracle Health Insurance supports handling of multiple requests (File Based Import) in one go. See How to Migrate Data Using a Data File Set for more details.

This API

A person batch request message has the following structure:

<persons>
  <person/> -- refer to Person Request for details
</persons>

A person batch response message has the following structure:

<personsResponse>
  <resultMessages/>
</personsResponse>

See the Activity Integration Point section in the HTTP API Integration Points part of the Developer Guide for more details. The elementId attribute that is included as part of the result messages element contains the code of the person for whom the messages are raised.

Data File Sets

Oracle Health Insurance also supports handling of multiple persons from a data file. See How to Migrate Data Using a Data File Set for more details.

Error Messages

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

Table 1. Error Messages
Code	Severity	Message
REL-IP-RELA-004	Fatal	Title code {code} is unknown.
REL-IP-RELA-005	Fatal	Tag type code {code} is unknown.
REL-IP-RELA-006	Fatal	Prefix code {code} is unknown.
REL-IP-RELA-008	Fatal	Language code {code} is unknown.
REL-IP-RELA-009	Fatal	Country code {code} is unknown.
REL-IP-RELA-010	Fatal	Bank code {code} is unknown.
REL-IP-RELA-011	Fatal	Bank account validation code {code} is unknown.
REL-IP-RELA-012	Fatal	Country region code {code} is unknown.
REL-IP-RELA-015	Fatal	Provider identified by code {code} and flex code definition code {code} is unknown.
REL-IP-RELA-016	Fatal	Provider assignment type code {code} is unknown.
REL-IP-RELA-017	Fatal	Capitation contract code {code} is unknown.
REL-IP-RELA-018	Fatal	Identifier type code {code} is unknown.
REL-IP-RELA-019	Fatal	Address type code {code} is unknown.
REL-IP-RELA-020	Fatal	Gender identification code {code} is unknown.
REL-IP-RELA-021	Fatal	Waiver reason code {code} is unknown.
REL-IP-RELA-022	Fatal	Product code {code} is unknown.
REL-IP-RELA-023	Fatal	Covered service tier code {code} is unknown.
REL-IP-RELA-024	Fatal	There are pending changes to this person, updates not allowed.
REL-IP-RELA-025	Fatal	Marital status type Code {code} is unknown.
REL-IP-RELA-026	Fatal	Relation link type code {code} is unknown.
REL-IP-RELA-027	Fatal	Multiple relations matched on identifier {identifier}.

In addition, functional business rule messages and standard messages related to dynamic fields and records may be returned. See Response Messages for more information.

1. Oracle Health Insurance generates a unique code using a dynamic logic function of the signature Person Code Generation. If no dynamic logic function with this signature exists, the code is set to the ID.