Group Client Integration Point

The system facilitates through this synchronous integration point the creation of a group client and its details (for example group accounts, group account products, premium bill allocations, etc.) by an external system. Through this integration point an external system can:

• Create a group client and its details ^[1]

• Update a group client and its details

The path looks like this:

 http://<host>:<port>/<contextRoot>/groupclients

This integration point is protected by access restriction "group clients IP".

Request Messages

Each request message may contain the details of one group client. The external interfaces will create request messages for the initial data load, in response to entry of new group clients and updates to previously sent group clients. The details of exactly what information needs to be in a given request message varies based on factors such as whether details have been sent before, and the category of details that have been added or updated.

The system accepts the request in the following format:

{
 "code": "",
  "descr": "",
 "displayName": "",
  "status": "",
 "parentGroupClientCode": "",
 "employerOrganizationCode": "",
  "billReceiverOrganizationCode": "",
  "amountDistribution": "",
  "partialPeriodResolution": "",
  "enrolledDaysThreshold": "",
  "contactRelationCode": "",
  "representativePersonCode": "",
 "groupClientCollectionSettingList": [
    {
      "advanceLength": "",
      "advanceUom": '',
      "spanReferenceDate": "",
      "startDate": "",
      "endDate": "",
      "policyCalculationPeriods": "",
      "calculationPeriodLength": "",
      "calculationPeriodUom": "",
      "collectionMethodCode":""
    }
  ],
 "groupClientBillingAccountList": [
    {
      "code": "",
      "descr": "",
      "contactRelationCode": "",
      "default": ""
    }
  ],
 "groupClientBrokerAgentList": [
    {
      "enrollmentProductCategoryCode": "",
      "brokerCode": "",
      "agentCode": "",
      "startDate": "",
      "endDate": ""
    }
  ],
 "groupClientPremiumScheduleList": [
    {
      "enrollmentProductCode": "",
      "enrollmentProductCategoryCode": "",
      "premiumScheduleCode": "",
      "startDate": "",
      "endDate": ""
    }
  ],
 "groupClientAdjustmentList": [
    {
      "enrollmentProductCode": "",
      "enrollmentProductCategoryCode": "",
      "scheduleDefinitionCode": "",
      "sequence": "",
      "startDate": "",
      "endDate": ""
    }
  ],
  "groupClientEventList": [
    {
      "descr": "",
      "eventDateTime": "",
      "policyCode": "",
      "groupAccountCode": "",
    }
  ],
  "groupAccountList": [
    {
      "code": "",
      "descr": "",
     "displayName": "",
      "startDate": "",
      "amountDistribution": "",
      "partialPeriodResolution": "",
      "enrolledDaysThreshold": "",
      "dataAccessGroupCode": "",
      "contactRelationCode": "",
      "groupAccountTimePeriodList": [
        {
          "displayName": "",
          "startDate": "",
          "endDate": ""
        }
      ],
      "groupAccountInsurableClassList": [
        {
          "insurableClassCode": ""
        }
      ],
     "groupAccountCollectionSettingList": [
        {
          "advanceLength": "",
          "advanceUom": '',
          "spanReferenceDate": "",
          "startDate": "",
          "endDate": "",
          "policyCalculationPeriods": "",
          "calculationPeriodLength": "",
          "calculationPeriodUom": "",
          "collectionMethodCode":""
        }
      ],
     "groupAccountBrokerAgentList": [
        {
          "enrollmentProductCategoryCode": "",
          "brokerCode": "",
          "agentCode": "",
          "startDate": "",
          "endDate": ""
        }
      ],
      "brokerAgentSwitchRuleList": [
        {
          "commissionExistingEnrollment": "",
          "commissionNewEnrollment": "",
          "thirdPartyRelationCode": "",
          "startDate": "",
          "endDate": ""
        }
      ],
     "groupAccountPremiumScheduleList": [
        {
          "enrollmentProductCategoryCode": "",
          "premiumScheduleCode": "",
          "startDate": "",
          "endDate": ""
        }
      ],
     "groupAccountAdjustmentList": [
        {
          "enrollmentProductCategoryCode": "",
          "scheduleDefinitionCode": "",
          "sequence": "",
          "startDate": "",
          "endDate": ""
        }
      ],
     "groupAccountProductList": [
        {
          "enrollmentProductCode": "",
          "displayName": "",
          "displaySequence": "",
          "amountDistribution": "",
          "partialPeriodResolution": "",
          "enrolledDaysThreshold": "",
          "groupAccountProductPremiumScheduleList": [
            {
              "premiumScheduleCode": "",
              "startDate": "",
              "endDate": ""
            }
          ],
          "groupAccountProductAdjustmentList": [
            {
              "scheduleDefinitionCode": "",
              "sequence": "",
              "startDate": "",
              "endDate": ""
            }
          ],
          "groupAccountProductProviderGroupList": [
            {
              "providerGroupCode": "",
              "assignedProviderGroupLabelCode": "",
              "startDate": "",
              "endDate": ""
            }
          ],
          "parameterDomainList": [
            {
              "parameterAliasCode": "",
              "discrete": "",
              "numberOfUnits": "",
              "percentage": "",
              "serviceDays": "",
              "amount": {
                "value": "",
                "currency: ""
              },
              "startDate": "",
               "endDate": ""
              },
              "parameterDomainValueList": [
                {
                  "default": "",
                  "dynamicLogicCode": "",
                  "numberOfUnits": "",
                  "percentage": "",
                  "serviceDays": "",
                  "amount": {
                    "value": ""
                  }
                }
              ]
            }
          ],
          "groupAccountAvailableProductList": [
            {
              "groupAccountTimePeriodStartDate": "",
              "insurableClassCode": ""
            }
          ]
        }
      ]
    }
 ],
  "premiumBillAllocationList": [
    {
      "groupAccountCode": "",
      "insurableClassCode": "",
      "scheduleDefinitionCode": "",
      "premiumScheduleTypeCode": "",
      "enrollmentProductCode": "",
      "enrollmentProductCategoryCode": "",
      "addOnCode": "",
      "startDate": "",
      "endDate": "",
      "active": "",
     "billReceiverList": [
        {
          "dynamicLogicCode": "",
          "groupClientBillingAccountCode": "",
          "percentage": ""
        }
      ]
    }
  ],
  "groupCommissionRateList": [
    {
      "groupAccountCode": "",
      "enrollmentProductCode": "",
      "enrollmentProductCategoryCode": "",
      "brokerCode":"",
      "agentCode":"",
      "percentage": "",
      "amountInterpretation="",
      "numberOfDays="",
      "amount": {
        "value": "",
        "currency: ""
      },
      "startDate": "",
      "endDate": ""
    }
  ]
}

For a description of the properties refer to the Data Model section in the Enrollment guide.

Submit for Processing

This request enables an external system to save or save-and-submit a group client. The URI that is used determines how the system processes the request. Use URI:

• /groupclients to save the group client but not submit it yet

• /groupclients/submit to save the group client and immediately submit it

If the save-and-submit URI is used, the group client is submitted for processing immediately after creation or update. See Process Group Client for a detailed description of the processing flow.

Dynamic Fields and Dynamic Records

A given implementation of the OHI application could have dynamic fields and dynamic records added to the group client and related entities that need to be interfaced. For details on how external interfaces can provide values for dynamic fields and dynamic records in request messages and how they are handled by the OHI application, refer to Property Representation PUT POST.

Updating Group Clients

If a group client code exists then the group client is updated as per the data provided in the request. When a group client is updated, single value attributes are handled as specified in Property Representation PUT POST. Details are handled in a different way than the standard replacing mechanism, because updates to details may require a recalculation of premium, or a new output document as described in the Change Events implementation guide.

The group client status can only be set from Approved to Changed. To change the status from Changed to Approved submit the 'Process group client' operation for this group client'.

Instead of replacing the entire list of details when a group client is updated, the details in the request message are matched with the existing details on specific attributes (see below). Existing details that match with details in the request are updated (only if there is a change), details in the request that do not match with existing details are inserted and existing details that do not match with details in the request are deleted. If the list element is not included, no changes to current details are made. If an empty list element is included, all current detail records are removed. This applies to the following lists of details:

• Group Client Level

  • Group Client Collection Settings: matched on start date

  • Group Client Brokers Agents: matched on enrollment product category code and start date

  • Group Client Premium Schedules: matched on enrollment product category code, enrollment product code, premium schedule code and start date

  • Group Client Adjustments: matched on enrollment product category code, enrollment product code, schedule definition code and start date

  • Premium Bill Allocations: matched on group account code, insurable class code, add-on code, schedule definition code, premium schedule type code, enrollment product code, enrollment product category code and start date

    • Bill Receivers: matched on premium bill allocation (see above), dynamic logic code and group client billing account code

  • Group Commission Rates: matched on group account code, enrollment product code, enrollment product category code, broker code, agent code and start date

  • Group Client Billing Account: matched on contact relation code

• Group Account Level

  • Group Account Time Periods: matched on group account (see above) and start date

  • Group Account Insurable Classes: matched on group account (see above) and insurable class code

  • Group Account Collection Settings: matched on group account (see above) and start date

  • Group Account Brokers Agents: matched on group account (see above), enrollment product category code and start date

  • Broker Agent Switch Rules: matched on group account (see above) and start date

  • Group Account Premium Schedules: matched on group account (see above), enrollment product category code, premium schedule code and start date

  • Group Account Adjustments: matched on group account (see above), enrollment product category code, schedule definition code and start date

  • Group Account Products: matched on group account (see above) and enrollment product code

  • Group Account Contact Relation: matched on contact relation code

• Group Account Product Level

  • Group Account Product Premium Schedules: matched on group account product (see above), premium schedule code and start date

  • Group Account Product Adjustments: matched on group account product (see above), schedule definition code and start date

  • Group Account Product Provider Groups: matched on group account product (see above), provider group code, assigned provider group label code and start date

  • Parameter Domains: matched on group account product (see above) and parameter alias code

    • Parameter Domain Values: matched on parameter domain (see above), amount value, number of units, percentage and service days

  • Group Account Available Products: matched on group account product (see above) and group account time period start date

Group Client Event details in the request are always inserted. There is no matching on existing records. If the same request is send in twice, the group client events will be inserted twice. Existing records will not be deleted if they don’t exist in the request. Only if an empty list is included, all current group client event detail records will be removed.

Group Client Messages cannot be added, updated or removed by this integration point.

Response Messages

This integration point will provide HTTP status codes as defined in Response Messages. If an error occurs, the appropriate HTTP status code is returned, and a notification is sent containing error details. The following error messages that are specific to the group client interface may be returned in the response messages:

Code	Severity	Message
POL-IP-GROC-001	Fatal	Group client code {code} is unknown
POL-IP-GROC-002	Fatal	Organization code {code} is unknown
POL-IP-GROC-003	Fatal	Broker code {code} is unknown
POL-IP-GROC-004	Fatal	Agent code {code} is unknown
POL-IP-GROC-005	Fatal	Enrollment product category code {code} is unknown
POL-IP-GROC-006	Fatal	Enrollment product code {code} is unknown
POL-IP-GROC-007	Fatal	Premium schedule code {code} is unknown
POL-IP-GROC-008	Fatal	Schedule definition code {code} is unknown
POL-IP-GROC-009	Fatal	Data access group code {code} is unknown
POL-IP-GROC-010	Fatal	Insurable class code {code} is unknown
POL-IP-GROC-011	Fatal	Provider group code {code} is unknown
POL-IP-GROC-012	Fatal	Assigned provider group label code {code} is unknown
POL-IP-GROC-013	Fatal	Parameter alias code {code} is unknown
POL-IP-GROC-014	Fatal	Dynamic logic code {code} is unknown
POL-IP-GROC-015	Fatal	Group account time period start date {start date} is unknown
POL-IP-GROC-016	Fatal	Group account code {code} is unknown
POL-IP-GROC-017	Fatal	Premium schedule type code {code} is unknown
POL-IP-GROC-018	Fatal	Add-on code {code} is unknown
POL-IP-GROC-019	Fatal	Group client billing account code {code} is unknown
POL-IP-GROC-020	Fatal	Third party relation code {code} is unknown
POL-IP-GROC-021	Fatal	Collection method {code} is unknown
POL-IP-GROC-022	Fatal	Contact relation {code} is unknown
POL-IP-GROC-023	Fatal	Group representative {code} is unknown

In addition, functional business rule messages may be returned as well as the standard messages related to dynamic fields and dynamic records. See also Response Messages. .

---

1. It is not possible to create or update group account add-ons, group account available product add-ons, group account product add-on overrides and group account product adjustment values through this integration point.