Policy Account Integration Point

Three integration points allow external systems to create, modify or retrieve information related to policy accounts and policy account transactions.

The Policy Account integration point supports

Create a policy account
Update dynamic fields of a policy account
Fetch a policy account

The Policy Account Transaction integration point supports

Create a policy account transaction for an existing policy account
Fetch policy account transactions of a policy account

The Policy Account Transaction List integration point supports

Create policy account transactions for a list of existing policy accounts

Note that it is not possible to delete a policy account or a policy account transaction through these integration point.

Create or Update Policy Accounts and Policy Account Transactions?

The external system can send a request to create or modify policy accounts and/or policy account transactions to a URL. For details on how values in the request messages are handled when a policy account is created or updated, refer to the concepts in the Integration Guide.

The external system also can send a file to create policy account transactions using the data file interface. Please refer to the 'File Based Import' section in the HTTP API Integration Points part of the Common Features book for more details.

Matching

Policy Accounts

The policy account number and the combination of policy, account definition and person drive whether a policy account is created or an existing policy account is updated.

If the account number and the combination of policy, account definition and person do not exist then a new policy account with the provided account number is added to the system.
If the account number already exists or the combination of policy, account definition and person already exists then the policy account’s details are updated as per the data provided in the request. Note that only the dynamic fields of the policy account can be updated.

Policy Account Transactions

The policy account transaction code drives whether only a new transaction needs to be created or that also an older transaction needs to be reversed. If the policy account transaction code does not exist, a new policy account transaction with the provided code is added to the system. If the account transaction code exists then the new account transaction is created and the existing transaction is reversed.

Policy account transactions are not updated by the integration point.

Policy Account

Create Policy Account

The external system can send a PUT request to create or modify a policy account to the URL: http://{base URL}/api/policyaccounts. The system accepts the request in the following format:

<policyAccount
  accountNumber=""
  policyAccountDefinitionCode=""
  policyCode=""
  personCode=""
/>

If the policy account does not exist it is created. If the PolicyAccountDefinitionCode or policyCode is empty, fatal message POL-IP-POLA-004 is raised.

The following values are set by default:

If the account number is empty, a new account number is generated by using the dynamic logic function defined for this purpose on the account definition.

The following rules apply:

A policy account can only be created if the policy (enrollment) has at least one enrollment product that specifies the account definition
A policy account with the period definition Group Account can only be created if (any version of) the policy is for a group account
A policy account can only refer to a person if the account definition is of level Person.
A policy account can only refer to a person that is enrolled on (any version of) on the policy account’s policy
If the message holds a policy account with an account number, policy code, account definition and person and in the system a policy account exists with either the same account number or the same combination of policy code, account definition and person but not in this combination, fatal message POL-IP-POLA-003 is raised.

For every policy account that is successfully created or updated, the system sends a response message in the same format as the request message.

Fetch a Policy Account

The external system can fetch a policy account and its balance by posting a request to the URL:http://{base URL}/api/policyaccounts.

Example:

GET http://{__contextroot__}/api/policyaccounts?accountNumber
='<accountNumber>'&policyCode='<policyCode>'&personCode=<personCode>&accountDefinitionCode=<accountDefinitionCode>&startDate=<startDate>&asOfDate=<asOfDate>&accountTransactionType=<accountTransactionType>
??

Either the account number or the combination policy code / account definition or the combination of policy code / account definition / person code are used to find the policy account.

If the account number is specified, only the account number is used to find the policy account.
If the account number is not specified, the combination of the policy, account definition and person code is used to find the policy account.
- If the account definition’s level is Policy, then only the policy and account definition codes are used to find a matching policy account.
- If the account definition’s level is Person, then the policy, account definition and person codes are used to find a matching policy account.

If account number and the combination of policy, account definition and person are filled, the system does not check the correctness of the combination.

If the accountTransactionType is provided in the request, the system will return the balance based only on the transactions of that transaction type. If no accountTransactionType is provided, all transaction types are included in calculating the account balance.

The startDate specifies the start date of a timeframe for selecting transactions in policy accounts with no time periods. This parameter is ignored for accounts with other time period definitions. For those accounts, the start date of the returned balance is always based on the applicable time period defined on the policy account.

The asOfDate specifies, in combination with the policy account definition period, the time period for which the transactions are included in the calculation of the account balance. If the asOfDate is omitted, the account balance for the system date is returned. All not-reversed transactions in a specific time period are included in the balance, not only the ones that have a transaction date that lays before the as-of date.

If no policy account transaction is found, the returned balance is 0.

Example

If time period CY2015 is from 01-Jan-2015 to 31-Dec-2015 and time period CY2016 is from 01-Jan-2015 to 31-Dec-2016 and the following transactions exist in the system:

Transaction Date

Transaction Amount

Transaction Type

Time Period

1-Jul-2015

400

PREM

CY2015

8-Sep-2015

-380

CLA

1-Oct-2015

400

PREM

1-Jan-2016

500

PREM

CY2016

15-Feb-2016

-450

CLA

If the request holds no transaction type the balance for any as-of date if is in 2015 is 420; the balance for any as-of date in 2016 is 50.

If the request is for the 'PREM' transaction type the balance for any as-of date if is in 2015 is 800; the balance for any as-of date in 2016 is 500.

See the Accounts section of the View and Edit Policies documentation for a description of how the account balance and the start- and end date of a policy balance are derived.

Once the request is acknowledged, the system processes the request and generates the response in the following format.

<policyAccountBalance
  accountNumber=""
  accountBalance=""
  balancePeriodStartDate=""
  balancePeriodEndDate=""
/>

Policy Account Transaction

Create Policy Account Transaction for an Existing Policy Account

An external system can create a policy account transaction for an existing policy account by posting a request to the URL: http://{base URL}/api//policyaccounttransactions.

The system accepts the request in the following format:

<policyAccountTransaction
   code=""
   descr=""
   policyAccountTransactionTypeCode=""
   personCode="">
   <amount/>
   <transactionDateTime>YYYY-MM-DDTHH:MM:SS</transactionDateTime>
   <policyAccount/>
</policyAccountTransaction>

Each element that represents an amount holds a fixed set of attributes. Consider the element below to clarify:

...
  <amount currency="USD">50</amount>
..

If the policy account transaction does not exist it is created.

If the account transaction code is empty, a new account transaction code is generated by dynamic logic function that is referenced by the policy account definition.
The transaction is by default created as not reversed, the reversal transaction date is empty
The currency of the amount must be the same as the currency of the policy account definition. If they are not the same the fatal message POL-IP-POLT-004 is raised.
The <policyAccount> element must contain attributes for either the account number or a combination of policy, account definition and person or both.
- If the policy account is not found the fatal message POL-IP-POLT-003 is raised.
- If the account number is not specified, the combination of the policy, account definition and person code is used to find the policy account instead.
  - If the account definition’s level is Policy, then the only policy and account definition codes are used to find a matching policy account.
  - If the account definition’s level is Person, then the policy, account definition and person codes are used to find a matching policy account. If the person code is empty, fatal message POL-IP-POLT-005 is raised.
    
    If the policy account is not found the fatal message POL-IP-POLT-003 is raised.
- If account number and the combination of policy, account definition and person are filled, the system does not check the correctness of the combination.

The following rules apply:

A policy account transaction can only refer to a person that is enrolled on (any version of) the policy account’s policy. A policy account transaction can only refer to a person if the account definition is of level Policy
The integration point only supports sending in transactions for an account transaction type that has the Manual indicator set to No. Fatal message POL-IP-POLT-002 is raised if the transaction references an account transaction type with Manual indicator set to Yes.

The following follow-up actions are executed:

If the policy account transaction’s type requires creating a general ledger event, this is generated by the dynamic logic function that is referenced by the policy account definition
If a policy account transaction with the same code already exists, the new transaction is saved to the system and the existing policy account transaction is reversed.

On successful creation of policy account transaction, the system responds with status 201 message.

Fetch Policy Account Transactions

Fetch Policy Account Transaction Lists for a Policy Account

The external system can fetch a list of policy account transactions for one policy account by posting a request to the URL: http://{base URL}/api/policyaccounttransactions.

Example: GET http://{contextroot}/api/policyaccounttransactions?accountNumber='<accountNumber>'&policyCode='<policyCode>'&personCode=<personCode>&accountDefinitionCode=<accountDefinitionCode>&asOfDate=<asOfDate>&accountTransactionType=<accountTransactionType> ??

For the usage of the parameters see the 'Fetch a Policy Account' section in this document.

Once the request is acknowledged, the system processes the request and generates the response.

<items>
  <policyAccountTransaction
    code=""
    policyAccountTransactionTypeCode=""
    personCode="">
    <transactionDateTime/>
    <amount/>
    <policyAccount/>
  </policyAccountTransaction>
</items>

The list of policy account transactions also includes the reversed transactions.

Policy Account Transaction Lists

Create Policy Account Transactions for Existing Policy Accounts

An external system can send in lists of policy account transactions for existing policy accounts. Because the volume of data can become quite extensive, these are file based requests. Please refer to the 'File Based Import' section in the HTTP API Integration Points part of the Common Features book for more details.

The system accepts the request in the following format:

<policyAccountTransactionList>
  <policyAccountTransaction
    code=""
    descr=""
    policyAccountTransactionTypeCode=""
    personCode="">
    <amount/>
    <transactionDateTime/>
    <policyAccount/>
  </policyAccountTransaction>
</policyAccountTransactionList>

The values to be set, the rules that apply and the follow-up actions are the same as in the policy account transaction IP.

This file based import needs as seed data:

Activity Types

Code	Description	Type Level	Top Level?	UI?	Dynamic Record Definition
LOAD_POL_ACC_TRANSACTIONS	Load policy account transactions	GL	Y	Y	FILE_IMPORT

Code

Description

Type Level

Top Level?

UI?

Dynamic Record Definition

LOAD_POL_ACC_TRANSACTIONS

Load policy account transactions

FILE_IMPORT

Dynamic Fields

A given implementation of the OHI application could have dynamic fields added to the policy account and policy account transactions that need to be interfaced. For details on how external interfaces can provide values for dynamic fields in request messages and how they are handled by the OHI application, refer to the concepts in the Integration Guide.

Messages

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

Code	Severity	Message
POL-IP-POLA-001	Fatal	Policy account definition code {code} is unknown
POL-IP-POLA-002	Fatal	Policy code {code} is unknown
POL-IP-POLA-003	Fatal	The combination of account number {account number}, policy code {code}, account definition {code} and person {code} is unknown
POL-IP-POLA-004	Fatal	Not enough information to create the policy account
POL-IP-POLA-005	Fatal	Start date must be before or on the as of date
POL-IP-POLT-001	Fatal	Policy account transaction type {code} is unknown
POL-IP-POLT-002	Fatal	Policy account transaction type {code} must not be of type Manual
POL-IP-POLT-003	Fatal	Policy account with {account number} {policy code} {account definition code} {person code} is unknown
POL-IP-POLT-004	Fatal	Currency code of the account transaction {code} must be the same as the currency code of the account definition {code}
POL-IP-POLT-005	Fatal	If the account number is omitted a person code is required to find the correct policy account at person level

Code

Severity

Message

POL-IP-POLA-001

Fatal

Policy account definition code {code} is unknown

POL-IP-POLA-002

Fatal

Policy code {code} is unknown

POL-IP-POLA-003

Fatal

The combination of account number {account number}, policy code {code}, account definition {code} and person {code} is unknown

POL-IP-POLA-004

Fatal

Not enough information to create the policy account

POL-IP-POLA-005

Fatal

Start date must be before or on the as of date

POL-IP-POLT-001

Fatal

Policy account transaction type {code} is unknown

POL-IP-POLT-002

Fatal

Policy account transaction type {code} must not be of type Manual

POL-IP-POLT-003

Fatal

Policy account with {account number} {policy code} {account definition code} {person code} is unknown

POL-IP-POLT-004

Fatal

Currency code of the account transaction {code} must be the same as the currency code of the account definition {code}

POL-IP-POLT-005

Fatal

If the account number is omitted a person code is required to find the correct policy account at person level

In addition, functional business rule messages may be returned as well as the standard messages related to dynamic fields and dynamic records (refer to the 'Response Messages' section in the HTTP API Integration Points part of the Common Features book).