Subscribers and Dependents

Load member(s) to an existing Group so the member can be digitally managed

In order to load demographic information about subscribers and their dependents:

1. Formulate the Request

2. Send Request / Receive Response

3. Check the Status

Formulate the Request

Subscribers and their dependents demographic and employment information can be loaded in together in a single request to Ideon.

Dependents can also be added to an existing subscriber.

Subscriber Load Request Body:

{
    "subscriber":
    {
        "external_identifier": "ABC-132A54",
        "location_id": "UUID",
        "first_name": "John",
        "last_name": "Smith",
        "social_security_number": "222222222",
        "gender": "male",
        "marital_status": "registered_domestic_partner",
        "birth_date": "1991-01-01",
        "class": {
            "employment_classification_id": "EMPLOYMENT_CLASSIFICATION_UUID",
            "effective_date": "2020-01-01"
        },
        "employment_details":
        {
            "start_date": "2019-01-01",
            "status": "full_time",
            "annual_earnings": 23000000,
            "earnings_effective_date": "2019-11-13",
            "wage_frequency": "annually",
            "hours_per_week": 40.0
        },
        "residential_address": {...},
        ,
        "dependents": [
            {
                "external_identifier": "Dependent1",
                "first_name": "Joanna",
                "last_name": "Smith",
                "social_security_number": "333333333",
                "gender": "female",
                "subscriber_relationship": "registered_domestic_partner",
                "birth_date": "1992-02-03"
            }
        ]
    }
}

Send Request / Receive Response

The request is sent to Ideon using a POST to the /groups/:id/subscribers endpoint. This ID used in the URL is the Ideon ID returned to the platform during group load.

Ideon will provide one of two responses to the requestor. The first option is that the request was received successfully: 201 - Resource Created Successfully. The second option is that syntax and semantic errors exist including the violation of carrier specific business rules: 422 - Unprocessable Entity.

Success

If the request passes validation the record will be pended for submission to a carrier. The platform will be informed of the pending status, and a copy of the subscriber record will be included in the response body.

{
    "status": "pending",
    "status_datetime": "2019-01-25T23:20:50Z",
    "subscriber":
    {
        "external_identifier": "ABC-132A54",
        "id": "a37ecd06-5d97-46e4-9b4e-dcde6a03246f",
        ...
        "dependents": [
        {
            "external_identifier": "Dependent1",
            "id": "a37ecd06-5d97-46e4-9b4e-dcde6a03246f",
            ...
        }]
    }
}

Errors

If errors are detected on the payload based on the expectations of the carrier receiving the enrollment then a response indicating the errors will be returned.

{
    "errors": [
    {
        "error_type": "invalid_request.parameter_required",
        "message": "The parameter is missing and is required",
        "parameter": "first_name"
    }]
}

Check the Status

A request can be made via a GET /subscribers/{id} to retrieve the status of the subscriber. Ideon will transmit the loaded subscriber to the carrier in the carriers proprietary format. The status of the subscriber will be pending until transmitted to the carrier. After transmission to the carrier, the subscriber's status will be submitted. After submission a subscriber can move to one of three states: pending, synced, or errors.

The subscriber's status covers all errors for the familial unit (subscriber and dependents). If there is an issue with the enrollment for a dependent the error will be reported and associated with the subscriber.

Synced

The status will be marked as synced when a carrier accepts the enrollment without errors or requests for additional documentation.

This status could also be used to indicate that the coverage details sent in an initial_enrollment qualifying life event match those at the carrier.

A copy of the subscriber record that was sent to the carrier that received the synced status will be included in the response body.

GET /subscribers/{id}

Subscriber Status Response Body:

{
    "status": "synced",
    "status_datetime": "2019-01-25T23:20:50Z",
    "subscriber":
    {
        "external_identifier": "ABC-132A54",
        "id": "a37ecd06-5d97-46e4-9b4e-dcde6a03246f",
        ...
        "dependents": [
        {
            "external_identifier": "Dependent1",
            "id": "a37ecd06-5d97-46e4-9b4e-dcde6a03246f",
            ...
        }]
    }
}

Errors

The status of the subscriber will be marked errors when a carrier provides errors to Ideon based on the processing of the subscriber's enrollment. Any errors that are present will be represented in an array, and displayed alongside the subscriber record. Errors indicate action needs to be taken by the platform to update the subscriber record.

GET /subscribers/{id}

Subscriber Status Response Body:

{
    "status": "errors",
    "status_datetime": "2019-01-25T23:20:50Z",
    "errors": [
    {
        "error_type": "invalid_request.parameter_required",
        "message": "The parameter is missing and is required",
        "parameter": "first_name"
    }],
    "subscriber":
    {
        "external_identifier": "ABC-132A54",
        "id": "a37ecd06-5d97-46e4-9b4e-dcde6a03246f",
        ...
        "dependents": [
        {
            "external_identifier": "Dependent1",
            "id": "a37ecd06-5d97-46e4-9b4e-dcde6a03246f",
            ...
        }]
    }
}

Pending

A subscriber is pending after it is initially loaded. The subscriber's status will return to pending after any member changes are made that have not been submitted to the carrier. For example the status will change from errors , submitted, or synced upon receiving a qualifying life event or demographic update for the subscriber or any dependents. In the event a subscriber had errors, then after an update the status will be pending and an array of errors will no longer display.

GET /subscribers/{id}

Subscriber Status Response Body:

{
    "status": "pending",
    "status_datetime": "2019-01-25T23:20:50Z",
    "subscriber": {...}
}