Subscribers

Detailed mapping of the fields used in a POST request to create a subscriber. The schema below is used in the /coverage_periods/{id}/subscribers endpoint

Required Elements

These elements are Required when creating a subscriber using a POST request to the Ideon API.

Ideon	Usage and Mapping
external_identifier	This is an identifier that your system can use or generate to identify the subscriber. This is in addition to our id that we generate upon creation.
*location_id	This is a foreign key formatted reference to a primary or secondary location, the Ideon generated unique identifier referring to the associated resource.
*birth_date	This field contains the date of birth for the employee
*employment_details	This object contains many fields related to a member's Employment. A full Mapping Guide for Employment Details is available here. Required start_date status Conditionally Required end_date retirement_date annual_earnings wage_frequency hours_per_week compensation work_state Recommended if present original_start_date title benefit_salary benefit_salary_effective_date base_salary base_salary_effective_date Optional employee_identifier
*gender	This is a value representing the member's gender. Accepted values in the API are: female male non_binary unknown Ideon transmits unknown and non_binary as female when carriers only accept Binary values, per carrier instruction. For carriers with no specific non-binary value, we map non_binary to unknown if accepted.
*last_name	This is the legal last name of the employee.
residential_address	This is the address at which the member resides, their "home" address value. Required address_line_1 city zip Recommended if present address_line_2 state fips_county_code country_code Note: Ideon currently only supports domestic addresses for enrollments, the country code can be defaulted to USA (as it will be if not provided)
*social_security_number	This is the employee's social security number. When sending a subscriber social security number, it cannot match another member's social_security_number in that same Group.

Conditionally Required Elements

While the elements above are required, there are additional common elements that your system will likely always have available.

We ask you provide these common values if available, as these can be required by Carriers on their data transmissions.

These elements are Recommended

Ideon	Usage and Mapping
first_name	This is the legal first name of the employee.
middle_name	This is the legal middle name of the employee. It is best to include this information if accurate and present in your system.
phone_numbers	This field allows a platform to send email addresses for a given member. These are associated with a type - personal, work, other - and are useful for member communications. Validation: minLength: 10 maxLength: 15 Example: 12223334444
emails	This field allows a platform to send email addresses for a given member. These are associated with a type - personal, work, other - and are useful for member communications. Validation pattern: ^.@.$ Example: [e-mail]
mailing_address	This is the address at which the member receives mailed communications. If this mailing address differs from the residential, it is essential to provide it. However, Mailing Address can always be provided, as Ideon's system will determine for which carriers it should be transmitted. Required address_line_1 city zip Recommended if present address_line_2 state fips_county_code country_code Note: Ideon currently only supports domestic addresses for enrollments, the country code can be defaulted to USA (as it will be if not provided)
marital_status	This is the value for the marital status of the member, whether they are considered: divorced single married registered_domestic_partner separated widowed
tobacco_use	This value shows whether a member is a current tobacco user for the purposes of plan eligibility. This is often required for Medical plans and Critical Illness plans that are "tobacco-rated". If present, it's helpful to provide across members, unless you only sell/enroll in "uni-smoker" rated products.

Dependents

A dependent can be created by providing the dependent alongside the subscriber. They can also be created independently, via a POST to subscribers/{id}/dependents.

The Mapping Guide for Dependents has a full enumeration of the elements needed to create a dependent.

The response schema for subscribers will always contain created dependents (alongside QLEs which refer to dependent coverage)

Employment Classifications

The subscriber request can also contain references to Employment Classifications, in the fields:

• division

• department

• class

• subgroup

• region

These fields allow a platform to associate a given Class or Division to a specific member, once created via a POST to groups/{id}/employment_classifications.

The Mapping Guide and FAQ for Employment Classifications has a full enumeration of the elements needed to create an employment classification.

Helpful Elements

We ask you provide these common values if available and consistent, as these can be very useful when assigning categories or identifiers to specific employees.

These elements are Optional

Ideon	Usage and Mapping
substance_abuse	Does the member have a history of substance abuse as relevant to their eligibility? Accepted values: true, false
work_location	This value is the name of a member's work location, within the employer's organization. Example: Boston Office
union	This value expresses whether a member is a union or non_union employee.
exempt	This value indicates whether the member is exempt from overtime, per state/federal regulations. Accepted values: exempt, non_exempt
name_prefix	This is a string field to express a prefix, such as Mr, Dr, etc
name_suffix	This is a string field to express a suffix, such as Jr or Sr
administrative	Is the member an administrative employee? Accepted values: administrative, non_administrative
executive	Is the member an executive employee? Accepted values: executive, non_executive
management	Is the member an employee in management? Accepted values: management, non_management
owner	Is the member a company owner? Accepted values: true, false
president	Is the member the company president? Accepted values: true, false

Additional Optional Elements

These fields are Optional, and Uncommon

Ideon	Usage and Mapping
citizenship_status	What citizenship status is the employee? Accepted values: alien, alien_non_resident, alien_resident, illegal_alien, us_citizen, us_citizen_non_resident, us_citizen_resident
bargaining	Is the member a bargaining or non-bargaining employee? Accepted values: bargaining, non_bargaining
highly_compensated	Does the employee fall into the tax classification "highly compensated"? Accepted values: true, false
salary_grade	What is the salary grade of the employee? This field is a text field.
languages	This is an array to represent one or more languages spoken by the member, which could be used to drive communication preferences. Each entry in the array contains language - a text field for each language, a language_proficiency reading, writing, speaking, native_language
medicare	This object captures information related to Medicare coverage and eligibility. Accepted values medicare_beneficiary_identifier eligibility eligibility_start_date enrolled coverages
key_employee	Is the member classified as a key employee? Accepted values: true, false
handicapped	Does the member have a disability? / Is the member disabled? Accepted values: true, false
height	This is a height value for the member, expressed in inches. This field takes an integer value - i.e. 60
weight	This is a height value for the member, expressed in pounds (lb). This field takes an integer value - i.e. 175
race_ethnicity	This is a field to express the member's race and ethnicity value. Accepted values: not_provided, not_applicable, asian_or_pacific_islander, black, caucasian, subcontinent_asian_american, other_race_or_ethnicity, asian_pacific_american, native_american, hispanic, american_indian_or_alaskan_native, native_hawaiian, black_non-hispanic, white_non_hispanic, pacific_islander

See Additional Documentation for links to our current API documentation.