---
description: >-
  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
---

# Subscribers

## Required Elements&#x20;

These elements are <mark style="background-color:red;">Required</mark> when creating a subscriber using a POST request to the Ideon API.

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





## Conditionally Required Elements&#x20;

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

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

These elements are <mark style="background-color:purple;">**Recommended**</mark>

<table><thead><tr><th width="248">Ideon</th><th>Usage and Mapping</th></tr></thead><tbody><tr><td>first_name</td><td>This is the legal first name of the employee. </td></tr><tr><td>middle_name</td><td>This is the legal middle name of the employee. It is best to include this information if accurate and present in your system.</td></tr><tr><td>phone_numbers</td><td>This field allows a platform to send phone numbers for a given member. These are associated with a <code>type</code> - personal, work, other - and are useful for member communications. <br><br><em>Validation</em>:  minLength: 10 maxLength: 15<br><em>Example</em>: <code>12223334444</code></td></tr><tr><td>emails</td><td>This field allows a platform to send email addresses for a given member. These are associated with a <code>type</code> - personal, work, other - and are useful for member communications. <br><br><em>Validation pattern</em>:  <code>^.@.$</code> <br><em>Example</em>: john@work.com</td></tr><tr><td>mailing_address</td><td><p>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 <em>always</em> be provided, as Ideon's system will determine for which carriers it should be transmitted. <br><br><mark style="background-color:red;">Required</mark><br>address_line_1 <br>city<br>zip <br><br><mark style="background-color:purple;">Recommended</mark> if present<br>address_line_2 <br>state <br>fips_county_code <br>country_code<br> </p><p>Note: Ideon currently only supports domestic addresses for enrollments, the country code can be defaulted to USA (as it will be if not provided)</p></td></tr><tr><td>marital_status</td><td><p>This is the value for the marital status of the member, whether they are considered:<br></p><p>divorced<br>single<br>married<br>registered_domestic_partner<br>separated<br>widowed</p></td></tr><tr><td>tobacco_use</td><td><p>This value shows whether a member is a current tobacco user for the purposes of plan eligibility. <br><br>This is often required for Medical plans and Critical Illness plans that are "tobacco-rated". </p><p></p><p>This value is required for ICHRA enrollment.</p><p></p><p>For Group enrollment, If present, it's helpful to provide across members, unless you only enroll in "uni-smoker" rated products. </p></td></tr></tbody></table>

### 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](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&#x20;
* department
* class
* subgroup
* region

&#x20;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](employment-classifications) and [FAQ](../frequently-asked-questions/employment-classifications) 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 <mark style="background-color:green;">Optional</mark>

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



## Additional Optional Elements&#x20;



These fields are <mark style="background-color:purple;">Optional, and Uncommon</mark>

<table><thead><tr><th width="210">Ideon</th><th>Usage and Mapping</th></tr></thead><tbody><tr><td>citizenship_status</td><td>What citizenship status is the employee? <br><br>Accepted values:<br>alien, alien_non_resident, alien_resident, illegal_alien, us_citizen, us_citizen_non_resident, us_citizen_resident</td></tr><tr><td>bargaining</td><td><p>Is the member a bargaining or non-bargaining employee?<br></p><p>Accepted values:  bargaining, non_bargaining</p></td></tr><tr><td>highly_compensated</td><td>Does the employee fall into the tax classification "highly compensated"? <br><br>Accepted values: true, false</td></tr><tr><td>salary_grade</td><td>What is the salary grade of the employee? <br><br>This field is a text field. </td></tr><tr><td>languages</td><td><p>This is an array to represent one or more languages spoken by the member, which could be used to drive communication preferences. <br></p><p>Each entry in the array contains</p><ul><li><code>language</code> - a text field</li><li><p>for each <code>language,</code> a <code>language_proficiency</code></p><ul><li>reading, writing, speaking, native_language<br></li></ul></li></ul></td></tr><tr><td>medicare</td><td><p>This object captures information related to Medicare coverage and eligibility. <br></p><p>Accepted values</p><ul><li>medicare_beneficiary_identifier</li><li>eligibility</li><li>eligibility_start_date</li><li>enrolled</li><li>coverages</li></ul></td></tr><tr><td>key_employee</td><td>Is the member classified as a key employee?<br><br>Accepted values: true, false</td></tr><tr><td>handicapped</td><td>Does the member have a disability? / Is the member disabled?<br><br>Accepted values: true, false</td></tr><tr><td>height</td><td>This is a height value for the member, expressed in inches. This field takes an integer value - i.e. <code>60</code></td></tr><tr><td>weight</td><td>This is a height value for the member, expressed in pounds (lb). This field takes an integer value - i.e. <code>175</code></td></tr><tr><td>race_ethnicity</td><td>This is a field to express the member's race and ethnicity value. <br><br>Accepted values:<br>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</td></tr></tbody></table>



See Additional Documentation for links to our current API documentation.

