​

Group connections

Create a group connection request to manage groups through the Noyo platform.

In the group_data object for the create endpoint, use Humana’s carrier group ID for the carrier_group_id. The format expected is a 6-digit string.

​

Sandbox testing

Use the following special Humana carrier_group_ids to simulate different group connection statuses. Test group connections with these IDs will asynchronously update with the corresponding status within 10 seconds of submission.

Only the first three characters are evaluated to figure out the target status (e.g. 989 means noyo_review). Since group connections should be unique by a carrier ID and carrier group ID combination, you may use the final characters to iterate and test this interaction further.

​

Carrier configurations

Group, plan, and member configurations are where Noyo shares and receives details that are unique to a carrier. Every other part of Noyo’s payloads are standardized, but the configurations hold the unique fields and classifications that change from connection to connection. As part of preparing to connect to a new carrier, you need to understand the contents of each configuration and be sure your system is able to send the required data for each member.

​

Get the group configuration from Noyo

The group carrier configuration endpoint returns information about how the group is labeled and categorized within the carrier’s system. You can also see this data in the Command Center on a group’s detail page by clicking one of their carrier connections.

Groups will be configured with a carrier_group_id string, which is the primary group identifier with Humana, along with a list of one or more sub_groups to categorize employees enrolling in coverage.

{
    "group_id": "14386816-4ae8-4646-992e-a076c703f46b",
    "carrier_id": "4d4d815b-ae8f-430c-901f-1c9d5ee3f4f1",
    "configuration": {
        "sub_groups": [
            {
                "sub_group_description": "CA Employees",
                "sub_group_identifier": "11223344"
            },
            {
                "sub_group_description": "Non-CA Employees",
                "sub_group_identifier": "99887766"
            }
        ],
        "carrier_group_id": "123456"
    }
}

​

Get the plan configuration from Noyo

The details in the plan configuration should be used to map each Noyo plan to the corresponding plan in your own system. Importantly, each plan configuration has details about which populations are connected to an individual plan. Groups with multiple populations may link a plan with one or more of them.

{
    "plan": {
        "id": "95231a48-8829-4cf8-8610-3523d2d96077",
        "version": "96ed9ba3-f438-4cc2-ab28-723a397d3c7a",
        "group_enrollment_id": "ac0b0224-9281-460e-a7f9-def4f8d9e543",
        "carrier_id": "4d4d815b-ae8f-430c-901f-1c9d5ee3f4f1",
        "line_of_coverage": "add",
        "name": "add",
        "code": "",
        "plan_type": "basic",
        "effective_start_date": "2023-01-01",
        "effective_end_date": "9999-12-31",
        "status": "active",
        "eligible_member_types": ["all"],
        "waiting_periods": [
            {
                "waiting_period_enrollment_type": "new_member",
                "waiting_period_rule": "hire_date"
            },
            {
                "waiting_period_unit": "day",
                "waiting_period_enrollment_type": "current_member",
                "waiting_period_amount": 0,
                "waiting_period_rule": "after_waiting_period"
            }
        ],
        "termination_policy": "last_work_date",
        "volume_rules": {},
        "plan_configuration": {
            "sub_group_identifiers": ["123456"]
        },
        "created": 1695919280,
        "modified": 1705423234
    },
    "ge": {
        "id": "ac0b0224-9281-460e-a7f9-def4f8d9e543",
        "version": "06105238-e1a2-4bca-a5ba-8e2ec0aeb16b",
        "group_id": "e54a679c-101e-472f-bfe6-2ea1cfe342e5",
        "carrier_id": "4d4d815b-ae8f-430c-901f-1c9d5ee3f4f1",
        "line_of_coverage": "add",
        "status": "active",
        "open_enrollment_start_date": "2022-12-01",
        "open_enrollment_end_date": "2022-12-31",
        "open_enrollment_renewal_date": "2023-01-01",
        "effective_start_date": "2023-01-01",
        "effective_end_date": "9999-12-31",
        "created": 1695919280,
        "modified": 1705423234
    }
}

​

Send the member configuration to Noyo

Each member request sent to Noyo can contain a configuration section. Depending on each carrier’s requirements, you may need to use this section to include carrier-specific identifiers like classes, subdivisions, or bill groups. These go in the coverage block’s carrier_config section and ensure that members are enrolled in the correct coverages. Member snapshots missing a carrier_config section or with incorrect config data will result in a 422 error.

You may include a sub_group_identifier matching the corresponding value in the group carrier configuration. If the call omits this value, Noyo will attempt to resolve the correct sub group in cases where only one option is available for the employee.

{
    "sub_group_identifier": "99887766"
}

​

Carrier-specific behavior

• Humana cannot switch members’ dental, vision, or medical plans through the Noyo “modifying coverage” action alone on QLE or OE transactions; plan switches must include an “adding” action and a “removing” action. See the docs for details.
• To update the effective end date for a member who has been terminated, you must contact Humana directly. (Member requests that attempt to change these end dates will be completed without the change being made in the Humana system.)

​

Carrier-specific validations

• Noyo validates that all member requests adding basic Life coverage have volume amounts included.
• Noyo validates that each sub_group_identifier specified in the carrier_config is valid for the group.
• Noyo validates that all member requests adding or modifying coverage contain plans that are available to the sub group specified in the carrier_config.
• Humana applies USPS validation to all addresses submitted in demographic changes.

​

Connection Basics

​

Getting groups connected

New groups can be connected to Noyo after the initial enrollment has been provided to Humana via census file and the group number has been issued by their underwriting team in the welcome letter.

To expedite the connection process for groups with existing Humana coverage, please ensure that any previous data transfer methods are deactivated prior to requesting a connection through Noyo.

To connect a group to Noyo, simply request a connection by sending the group name and policy ID as outlined in the Technical Spec. Most connections are completed in 1–3 business days. Groups with 300+ people will be manually reviewed by Humana, which can extend the processing time of a connection request.

As with all other Sync carriers, we process a group connection by pulling all plan, member, and group structure data from Humana to populate our system.

If at any point we encounter an issue connecting the group, Noyo will work with Humana to resolve the issue. We may contact you if your input is needed, and these group connections may take longer to complete.

​

Groups are considered fully connected when:

• Noyo returns the connection status as “completed.”
• You’ve linked Noyo’s IDs for account structure information, plans, members, and coverages to your own, and established an account structure mapping process.
• You’ve deactivated previous forms of data exchange and are ready to send all enrollment changes through Noyo.

​

Processing member changes

Each member request is broken into one or more individual “transactions.” Our integrations with API-enabled Sync carriers generally result in 90% of member transactions arriving at the carrier within 10 minutes of being sent to Noyo, and 95% of transactions being confirmed by Noyo within 4 business days of original receipt.

​

Round-trip confirmation

As with other Sync carriers, Noyo is able to read data directly from Humana’s system. Noyo monitors each transaction with round-trip confirmation, which triggers a check in the carrier’s system after the change is sent and again on the change’s effective date to ensure that enrollments go through as expected.

Use the Tracking API to see the results of round-trip confirmation and get a granular view of how each change is being processed.

​

Managed changes

Our goal is to confirm all member changes within 4 business days. However, some transactions cannot be confirmed automatically after being submitted through our API because special handling is required. We call these “managed” transactions and they may have longer confirmation timelines.

Types of managed changes:

• SSN changes Adding an SSN or changing an existing one.
• Reinstatements Reinstating previously terminated members or members that have removed all coverage.

​

Retroactive changes

Humana applies the following rules to retroactive transactions; violations will be rejected and marked as “failed” in the Noyo system. Please reach out to the Humana billing team to request an exception to retro rules.

• New hires must be submitted within 31 days of the effective start date of their coverage.
• Terminations must be submitted within 60 days of the term date.
• For a Marriage QLE, dependents (spouse/children) must be added within 31 days of marriage.
• For a Loss of Coverage QLE, subscribers or dependents can be added within 31 days of the loss of coverage.
• For a Birth QLE, the child must be added to the plan within 31 days of birth (except in AR, FL, WA, and WI).

​

Failed transactions

The following changes cannot be completed through Noyo and will be marked as “failed” in our system:

• Date of hire changes
• Transactions to switch medical, dental, or vision plans that only include a “modifying coverage” action. See the Technical Spec for more about successful plan switches.

​

Other scenarios

• To update the effective end date for a member who has been terminated, you must contact Humana directly. (Member requests that attempt to change end dates will be completed without the change being made in the Humana system.)
• A member being terminated before their effective start date will automatically be enrolled in one month of coverage by default. For example: An employee was hired on 7/15/2024 and elected coverage effective 9/1/2024. The employee was terminated on 8/15/2024. Humana will automatically enroll the employee in one month of coverage and set the effective end date as 9/30/2024.
• A transaction with an event reason of “death” will not follow a group’s termination provisions. Humana’s policy for deaths is to terminate all coverages immediately, with the QLE event date as the effective end date for the employee.
• For Texas groups with medical coverage, state regulations (Texas SB51) prohibit retroactive coverage terminations. This can cause longer processing timelines, though Humana will honor the signature date sent from the platform even if the date is in the past.

​

Open enrollment

You can send the group’s plan-level renewal decisions to Noyo once they’ve been officially communicated to Humana. Noyo will check Humana’s system daily until the new plans are available to ensure that they are installed correctly.

When the plans in Humana’s system match the expectations you submitted, the renewal decision status will move to “ready” and you will be able to send member requests with each member’s open enrollment elections for the new plan year.

Humana’s OE window goes from 60 days before the first day of the OE month to 30 days after it. For example, for a 10/10 renewal, the OE window would be 8/2 to 10/31. Any enrollments outside of the OE window need to be sent to Humana directly. There are no blackout periods.

Open enrollment requests

New hire requests