Skip to main content
Several of the Noyo models track data elements that change over time. For example, a plan may only last for one year before being discontinued, or a member might have the same life plan for multiple years but change their coverage volume for that plan over time. The group carrier configuration, group plan, and individual enrollment models are all temporally tracked. Data at the group level is all sourced from the carrier. You can query this data to get an array of records tracking changes over time, but you cannot edit the data directly.  You are able to edit individual enrollments via member snapshots; see more on that below.  Demographic information for employees and dependents is not temporal; the current state of demographic data is the only state that exists in our system. You should always send the most recent state of demographic data, and we will transmit that to the carrier. For example, if you know someone’s salary will change in the future, send us that salary with an effective date in the future. The amount you send will be the only record of a salary for that person; any previous salary amounts will not be stored or queryable. 

​
Using temporal data in member snapshots

In member snapshots, each coverage has an enrolled_members list. Each enrolled member can include effective_start_date, effective_end_date, and optionally latest_change_effective_date; these dates determine the individual enrollment timeline for that member. The carrier_config on a coverage is assigned an effective date based on the coverage’s enrolled_members in this order:
  1. The system looks for the first enrolled member in list order where individual_type == "employee"
    • If that employee has latest_change_effective_date, that date is used
    • Otherwise, that employee’s effective_start_date is used
  2. If there is no employee in enrolled_members, the system uses the first enrolled member in the list, which should be a dependent.
    • If that dependent has latest_change_effective_date, that date is used
    • Otherwise, that dependent’s effective_start_date is used
The system does not sort enrolled members or choose the earliest or latest date. If multiple employee entries are included in the same coverage, only the first employee entry in enrolled_members is used to determine the carrier_config effective date. To represent changes during the year, provide separate effective periods. Coverage level fields such as carrier_config and cobra_details, and enrolled member fields such as volume, can then produce distinct temporal records.

​
Important concepts

  • effective_start_date - The original date that a member started coverage on a plan. When members are terminated and rehired, they get new effective start dates. This can differ from some other industry definitions, which define a new start any time benefits change. 
  • effective_end_date - The end date of coverage on a plan. Unless the coverage itself is ending, this should be set to datemax (9999-12-31). Read more here. 
  • effective_date - A query parameter for some endpoints that allow the user to specify the relative date for which to see the state of a record. 
  • latest_change_effective_date - The effective date of the temporal data contained within the coverage block. See below for example usage.

​
Example scenarios

​
Mid-year benefit class change

If an employee has a QLE on June 1st that changes their benefit class from A to B for a coverage that’s active from January 1st, there are two ways to represent this in the member snapshot payload.  Preferred method: one coverage block with a latest_change_effective_date Add a latest_change_effective_date to the enrolled member, and pass the new benefit class value in the carrier_config section. 
Example Request
{
    "coverages": [
        {
            "carrier_id": "3a070236-770e-4521-adf9-5c342d03ed36",
            "plan_id": "7c6de7e2-35a0-4ddf-a41b-c849a6569b49",
            "line_of_coverage": "dental",
            "carrier_config":{
                "benefit_class_identifier": "B"
            },
            "enrolled_members": [
                {
                    "individual_type": "employee",
                    "custom_individual_id": "1234567890",
                    "effective_start_date": "2025-01-01",
                    "effective_end_date": "9999-12-31",
                    "latest_change_effective_date": "2025-06-01"
                }
            ]   
        }
    ]
}
Alternative method: two coverage blocks with different effective_dates Edit the effective dates for each enrolled member in the original coverage block to January 1st through May 31st and leave the original carrier_config in place.  Then add a second coverage block with an effective date of June 1st, with the new benefit class defined in the associated carrier_config section.  This method is not recommended because specifying the previous state (benefit class A) can cause Noyo to attempt to fulfill that previous state at the carrier and thus run afoul of the carrier’s retro rules. For this example scenario, the user likely just wants to change the benefit class to B starting 6/1 and is not concerned with the earlier state.
Example Request
{
    "coverages": [
        {
            "carrier_id": "3a070236-770e-4521-adf9-5c342d03ed36",
            "plan_id": "7c6de7e2-35a0-4ddf-a41b-c849a6569b49",
            "line_of_coverage": "dental",
            "carrier_config":{
                "benefit_class_identifier": "A"
            },
            "enrolled_members": [
                {
                    "individual_type": "employee",
                    "custom_individual_id": "1234567890",
                    "effective_start_date": "2025-01-01",
                    "effective_end_date": "2025-05-31"
                }
            ]   
        },
        {
            "carrier_id": "3a070236-770e-4521-adf9-5c342d03ed36",
            "plan_id": "7c6de7e2-35a0-4ddf-a41b-c849a6569b49",
            "line_of_coverage": "dental",
            "carrier_config":{
                "benefit_class_identifier": "B"
            },
            "enrolled_members": [
                {
                    "individual_type": "employee",
                    "custom_individual_id": "1234567890",
                    "effective_start_date": "2025-06-01",
                    "effective_end_date": "9999-12-31"
                }
            ]   
        }
    ]
}

​
Open enrollment election

During open enrollment, employees may enroll in new coverages with future effective dates while still being enrolled in current-year coverage. To express this in a member snapshot, you should ensure that any coverages that are discontinuing have an effective_end_date set. Then add a new coverage block for each new enrollment and set the effective_start_date to the day after the current coverage ends.  Note that this specific scenario is often considered a “plan switch.”
Request
{
    "coverages": [
        {
            "carrier_id": "3a070236-770e-4521-adf9-5c342d03ed36",
            "plan_id": "7c6de7e2-35a0-4ddf-a41b-c849a6569b49",
            "line_of_coverage": "dental",
            "carrier_config": {},
            "enrolled_members": [
                {
                    "individual_type": "employee",
                    "custom_individual_id": "1234567890",
                    "effective_start_date": "2025-01-01",
                    "effective_end_date": "2025-12-31"
                }
            ]
        },
        {
            "carrier_id": "3a070236-770e-4521-adf9-5c342d03ed36",
            "plan_id": "4e5ebd0c-b5e4-4988-b93f-3e78ff6cf1b5",
            "line_of_coverage": "dental",
            "carrier_config": {},
            "enrolled_members": [
                {
                    "individual_type": "employee",
                    "custom_individual_id": "1234567890",
                    "effective_start_date": "2026-01-01",
                    "effective_end_date": "9999-12-31"
                }
            ]
        }
    ]
}

​
How carriers process temporal data

Carriers generally only process the current/latest state of a member’s data, which means that retroactive changes can be difficult for them to process. You can learn more about carrier-specific retro policies in our documentation in the Noyo web application, but in most cases we do not recommend sending changes to past data through Noyo.