> For the complete documentation index, see [llms.txt](https://ideonapi.gitbook.io/enrollment/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ideonapi.gitbook.io/enrollment/implementation-resources/scenarios/add-a-new-subscriber.md).
# Add a New Subscriber
This page describes how to add a new subscriber - whether the member is a New Hire or Newly Eligible for Benefits
## Checklist
* [ ] Determine Event in Platform System
* [ ] Map Elections
* [ ] Send Subscriber Demographics
* [ ] Store Member Id(s) and Check Status
* [ ] Send QLE Request(s)
* [ ] Store QLE Id(s) and Check Status
* [ ] Carrier Transmission
* [ ] Error Reporting
## Components
1. [Determine Event in Platform System](#determine-event-in-platform-system)
2. [Map Elections](#map-elections)
3. [Send Subscriber Demographics](#send-subscriber-demographics)
* [Store Member Id(s) and Check Status](#store-member-id-s-and-check-status)
4. [Send QLE Request(s)](#send-qualifying-life-event-request-s)
* [Store QLE Id(s) and Check Status ](#store-qle-id-s-and-check-status)
5. [Carrier Transmission](#carrier-transmission)
6. [Error Reporting](#error-reporting)
### Determine Event in Platform System
#### Description
In the Platform system, a user or process has identified a New Hire or a member newly electing benefits as they are now eligible.
#### Example 1
* A member is hired and that member elects benefits, starting the first of the next month.
* A request is created for the member and for each set of coverages with a Carrier
* These requests are sent to Ideon in real-time.
#### Example 2
* A member is hired, and that member is not eligible for any benefits.
* The nature of that employee's work changes, and they are now eligible for several benefits
* A request is created for the member and for each set of coverages with a Carrier
* These requests are sent to Ideon in real-time.
### Map Elections
#### Description
Given an employee and their family members,
If that member selects benefits for one or more carriers, which have a `coverage_period` with Ideon
Then the Platforms system should create `qualifying_life_events` for each set of coverages with a Carrier.
* If not stored as an association, fetch the created plan uuids by using a GET request to `coverage_periods/id`
* Otherwise map the elected options to a request, using the plan id to represent the elected plan option in your system
Example 1 - One Carrier:
* `Basic Life and AD&D`, `Short Term Disability` , and `Long Term Disability` with `guardian`
* This will be represented with **one** POST request to `subscriber/{{id}}/qualifying_life_events` , using a subscriber `id` , and including three product lines under a single Coverage Period
[Request](#request)
Example 2 - Multiple Carriers:
* `Medical` with `kaiser`
* `Dental` and `Vision` on `cigna`
* `Accident`, `Critical Illness` and `Hospital Indemnity` with `voya`
* This will be represented with **three** POST requests to `subscriber/{{id}}/qualifying_life_events` , all using that same subscriber `id` but for different Coverage Periods and product lines in the request body
Requests
{% hint style="info" %}
Mapping these options can be tricky depending on **How** your system represents Plan Options to it's users.
If your system splits-out a given "plan option" with the carrier by Covered Member Type, Coverage Tier, Classification, etc. you might have **many** Plan Options created in your system.
To reduce set-up time and the complexity of the configuration, we prefer these to be mapped "down" to base plan options in the Ideon system. However, we can accommodate these split plan options in set-up if needed.
{% endhint %}
### Send Subscriber Demographics
#### Description
Given a newly hired or eligible member that does not exist in Ideon's system for this Group, we would expect a POST request to create a new subscriber.
Class, Subgroup, and Dependents might not be present on the subscriber you are creating. In the example below, a Subscriber is created with a Class assignment, and Subgroup assignment.
Request:
```json
Create Subscriber
{
"subscriber": {
"external_identifier": "Subscriber1",
"location_id": "{{primary_location_id}}",
"first_name": "Employee Three",
"last_name": "Ideonu",
"birth_date": "1991-05-30",
"gender": "male",
"social_security_number": "{{ssn}}",
"employment_details": {
"start_date": "{{first_of_current_month}}",
"status": "full_time",
"annual_earnings": 10000000,
"earnings_effective_date": "{{first_of_current_month}}",
"wage_frequency": "weekly",
"compensation": "salary",
"hours_per_week": 40
},
"class": {
"employment_classification_id": "{{class_1_id}}",
"effective_date": "{{first_of_current_month}}"
},
"subgroup": {
"employment_classification_id": "{{subgroup_1_id}}",
"effective_date": "{{first_of_current_month}}"
},
"dependents": [
],
"residential_address": {
"address_line_1": "34 B Street",
"city": "Winchester",
"state": "VA",
"zip": "22603"
},
"mailing_address": {
"address_line_1": "34 B Street",
"city": "Winchester",
"state": "VA",
"zip": "22603"
},
"phone_numbers":[{
"type": "work",
"contact": "7777777777"
},
{
"type": "home",
"contact": "7777777777"
},
{
"type": "fax",
"contact": "7777777777"
}],
"emails":[{
"type": "work",
"contact": "be_square@gmail.com"
}]
}
}
```
#### Store Member Id(s) and Check Status
In order to refer to this subscriber later, and send coverages, your system should save the successful response body and store the `id` associated with the subscriber.
Check the Status of the request to determine if you received an Error on formatting or content of the request - an error that requires you to update the request body content or format is generally listed as Status `422`
* [ ] Save and analyze response
* [ ] Confirm Success Status
* [ ] If Failure, Store and Address this Failure
* [ ] Once addressed, Retry the Request
* [ ] Store the Response payload, particularly the `id` for later use
### Send Qualifying Life Event Request(s)
#### Description
In this example. the member is electing Basic Life /AD\&D and Disability coverages.
If you don't have the current member data and id for the subscriber, use a GET call on the Group retrieve the latest subscriber data for that Group
* `subscriber_id` -this refers to the `id` of the created subscriber
* `coverage_period_id` - this refers to the `id` of the created coverage period
* This is the link between the carrier and the subscriber
* `basic_life_add_plan_id` - this refers to the `id` of the created plan, in this case a Basic Life Add Plan
* `std_plan_id` - this refers to the `id` of the created plan, in this case a Short Term Disability Plan
* `ltd_plan_id` - this refers to the `id` of the created plan, in this case a Long Term Disability Plan
* `today` - is the date that the Platform system is generating the event
* `first_of_current_month` - this refers to a placeholder, The first of day of the current calendar month. This is commonly First of this month, Same Day, or First of the Next Month for new hires.
This would be created by sending a POST request to `subscriber/{{id}}/qualifying_life_events`
#### Request
```json
POST subscribers/{{subscriber_id}}/qualifying_life_events
{
"qualifying_life_event": {
"event": "new_hire",
"date": "{{today}}",
"eligibility_start_date": "{{first_of_current_month}}",
"coverage_period_id": "{{coverage_period_id}}",
"plan_elections": {
"life_accidental_death_dismemberment": {
"plan_id": "{{basic_life_add_plan_id}}",
"type": "election",
"coverages": [
{
"member_id": "{{subscriber_id}}",
"status": "employer_sponsored",
"start_date": "{{first_of_current_month}}",
"volume": 10000000
}
]
},
"short_term_disability": {
"plan_id": "{{std_plan_id}}",
"type": "election",
"coverages": [
{
"member_id": "{{subscriber_id}}",
"status": "employer_sponsored",
"start_date": "{{first_of_current_month}}",
"volume": 34500
}
]
},
"long_term_disability": {
"plan_id": "{{ltd_plan_id}}",
"type": "election",
"coverages": [
{
"member_id": "{{subscriber_1_id}}",
"status": "employer_sponsored",
"start_date": "{{first_of_current_month}}"
}
]
}
}
}
}
```
#### Store QLE Id(s) and Check Status
In order to confirm the status of this QLE and the easily refer to this exact request later, your system should save the successful response body and store the `id` associated with each QLE.
Check the Status of the request to determine if you received an Error on formatting or content of the request - an error that requires you to update the request body content or format is generally listed as Status `422`
* [ ] Save and analyze response
* [ ] Confirm Success Status
* [ ] If Failure, Store and Address this Failure
* [ ] Once addressed, Retry the Request
* [ ] Store the Response payload, particularly the `id` for later use
### Carrier Transmission
#### Description
* When Ideon receives this Subscriber coverage, we identify whether the member was previously enrolled by our system.
* In Test: Transmit the member to Ideon as well as in your current administration method. This is to ensure that both systems know the member's status and won't delay an enrollment for the member.
* In Production: Transmit the member to Ideon. We will:
* send an API request to enroll or rehire the member
* Store the members coverages but not re-enroll
* send the member on the next File Delivery to the Carrier (within 7 business days)