API: Requests, Snapshot COBRA: Supported Geographies: All Group Size: All Lines: accident, add, critical, dental, hospital, life, ltd, std, vision Name: Principal Network: Sync New Group Connection Time: 5–10 days PDF: Broker_Authorization_Form.pdf Unsupported: -

​

Group connections

To successfully manage a group through Noyo, send a group connection request containing the broker’s FEIN in the broker_federal_ein field and the group’s 7-digit policy number in the carrier_group_id field of the group_data object. The broker’s FEIN is required as an extra layer of authorization for sharing group data with Noyo, so it must match the BOR on file with Principal.

​

Sandbox testing

You may use the following special Principal Financial 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 policy_number string, which is the primary group identifier, along with a list of one or more member_groups and one or more bill_groups to categorize employees enrolling in coverage.

Some groups may also be configured with a bill_group_sort_class, which supports additional custom billing configurations.

{
    "group_id": "57c49148-408c-476c-a3ed-93dd8a01027b",
    "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
    "configuration": {
        "policy_number": "1234567",
        "member_groups": [
            {
                "member_group_key": 1122334,
                "member_group_status": "open",
                "member_group_name": "MBRS ELECTING HIGH DN PLAN"
            },
            {
                "member_group_key": 1122335,
                "member_group_status": "open",
                "member_group_name": "MBRS ELECTING HIGH DN PLAN"
            }
        ],
        "bill_groups": [
            {
                "bill_group_description": "All Members",
                "bill_group_number": 10001,
                "bill_group_status": "open"
            },
            {
                "bill_group_description": "COBRA Members",
                "bill_group_number": 10002,
                "bill_group_status": "open"
            }
            "bill_group_sort_classes": [
               {
                 "sort_class_key": 2215528,
                 "sort_class_name": "Beehive3D Inc."
               },
               {
                 "sort_class_key": 2224658,
                 "sort_class_name": "Eagle Engineered Solutions"
               },
               {
                 "sort_class_key": 2215525,
                 "sort_class_name": "Volunteer Aerospace, LLC"
               },
              ]

        ]
    }
}

​

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.

Some Principal plans are only available for employees in certain member groups. Principal plans will include a plan_configuration block with a member_group_keys field containing a list of integers. The member group keys will match the member groups in the Group Carrier Configuration section and describe which member groups are eligible to enroll in the plan.

​

Send the member configuration to Noyo

Each member snapshot or 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.

Member requests or snapshots may include optional member_group and bill_group integers matching the member_group_key and bill_group_number options listed in the group carrier configuration. If you omit either of these values, Noyo will attempt to resolve the correct bill group and member group in cases where only one option is available for the employee.

If there are multiple options for bill_group_number or multiple options for member_group_key, requests need to include a value for bill_group or member_group.

For groups configured with a bill_group_sort_class, all requests must include a sort class for each member.

{
    "member_group": 1122335,
    "bill_group": 10001,
    "sort_class": "sortclass"
}

​

Carrier-specific behavior

• It’s best practice to send salary amounts whenever they’re available. However, Principal does not store salaries for groups and members without salary-based coverage, so this information may not always be available for confirmation in the Noyo system.
• Changes to salary-based coverages (most commonly basic life and disability) must include a salary amount, otherwise the final election amount may be inaccurate or the transaction may take longer to process.
• Principal only supports the gender markers M or F.

​

Events and effective dates in member snapshots

Principal calculates effective dates based on the event type, date submitted, and waiting period rules. To ensure accurate effective dates, you’ll need to submit all member snapshots with a complete events block (snapshots without this block will be rejected with an error message). Principal will calculate the effective date of coverage, which Noyo brings into our system. You can see the calculated effective date by getting enrollments for employees and dependents.

For more detail and examples of how Principal calculates effective dates, see the Connection Basics section below.

​

Coverage start and end dates

Changes to coverage start and end dates cannot be made through Noyo, but it is still important to include start and end dates in your calls to ensure that other carriers associated with the member receive this data.

​

Volume amounts

If you do not apply the correct rounding rules to volume amounts, the Noyo system may reflect Principal’s application of the correct rules instead of the amounts you sent. Rounding rules should be encoded in your system during group setup.

Principal will automatically apply age reduction rules to adjust coverage amounts for members aged 65 and older. The adjusted amount is what will be confirmed and displayed in the Noyo system. You should send the full benefit amount without the age reduction logic included. For example, a member with $50,000 in basic life coverage will have the amount automatically adjusted down to$32,500 when they turn 65 according to Principal’s 35% benefit reduction logic.

​

Hospital indemnity coverage

There can be multiple hospital indemnity plans per group, and this is the only line of coverage where there can be multiple plans per member type in the same group (i.e., two plans for employees and two plans for spouses). The plans are differentiated by the choice_plan_description property. This property is exposed in the plan_configuration for hospital indemnity plans as follows:

{
    "member_group_keys": [3066936, 3066937, 3066938, 3066935],
    "choice_plan_description": "ONE"
}

Plan switches require that the original coverage be terminated the day before the start date of the coverage on the new plan.

​

Validations

• Noyo checks that each bill group and member group specified in the carrier_config is valid for the group.
• Noyo validates that all requests to add or modify coverage contain plans that are available to the bill group and member group specified in the carrier_config.
• Noyo validates that all member requests adding life, AD&D, and critical illness coverage have volume amounts included.

​

Connection Basics

​

Getting groups connected

To connect a new or existing group to Noyo, simply request a group connection with the group name, policy number, and broker FEIN as defined in the Technical Spec.

​

New groups

Net-new groups to Principal can be connected to Noyo as soon as they are built into Principal’s administration system. Brokers without existing Noyo-Principal groups will need to sign an Authorization to Release Information form and return it to us at support@noyo.com. The form does not need to be signed for any subsequent groups as long as the FEIN is correctly submitted.

​

Existing groups

Principal only allows one data connection per group; please ensure that any previous or existing file connections are deactivated before submitting a group connection request.

​

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 change is broken into one or more individual “transactions” for the changes that need to be made with each carrier. 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 Principal’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.

Principal managed transactions are generally resolved in 5-10 business days. Note that when broker involvement is required, the turnaround time is dependent on how quickly the broker can provide information.

Types of managed changes

• Gender changes Changing the gender marker for a member or dependent
• Effective or hire date changes Editing the effective date of coverage or the hire date of a member
• Bill or member group Changes to the bill or member group a member belongs to
• Reinstatements Reinstating previously terminated members, dependents, or members that have removed all coverage
• Volume amounts Changes to the volume amount associated with group or voluntary life/AD&D coverage

​

Failed changes

The following changes will automatically fail due to Principal’s system logic. It’s still best practice to send these changes to Noyo in case they are accepted by other carriers the group has coverage with:

• Demographic changes for terminated members
• Dependent address changes
• Requests to remove coverages for an already terminated member

​

Retroactive changes

Coverage changes must be sent within 31 days of the precipitating event (such as a QLE or hire date). Late changes to contributory/voluntary benefits will go into effect as of the next OE period. Late changes to non-contributory benefits (100% paid by the employer) will go into effect as of the initial eligibility date.

For retroactive voluntary life or voluntary STD/LTD enrollments, Principal will likely request an evidence of insurability (EOI) form. The transaction will be completed in our system but the correct coverage will not be visible until the member has submitted EOI. We run regular data syncs to pull in these enrollments once EOI is complete and update our system with the correct coverage.

​

COBRA

COBRA support is available for Dental and Vision in all states, and Life in Minnesota and Montana. Although PFG offers both group and individual billing options for COBRA, the Noyo connection currently only supports group billing. Check out our guide for more information on transmitting COBRA changes.

​

EOI

Evidence of insurability (EOI) may be required for Basic Life/ADD, STD, LTD, Voluntary Life/ADD, and Voluntary Critical Illness coverages.

​

Dependent requirements

If an employee is enrolled in critical illness coverage, their children will be automatically enrolled with a coverage amount equaling 25% of the employee’s critical illness amount. However, this will not be reflected as a separate individual enrollment on the employee or dependent’s record.

​

Effective dates and enrollment timelines

Principal calculates their own effective dates using the event type and date of the enrollment plus the group’s waiting period rules. Any effective date mismatches between what you submit and what is confirmed by Noyo must be resolved directly with Principal.

The following examples illustrate how the event date and “timeliness” of enrollments impact effective dates.

New hires

A group has a 30-day waiting period and a “first of coinciding/following month” effective date rule. The employee was hired on March 15th.

If the event date is on or before the eligibility date of May 1st, the member’s enrollment is timely and all coverage will be effective May 1st. If the event date is between the eligibility date and the 30-day grace period that runs from May 2nd to May 31st, the enrollment is still considered timely, but effective dates could be different for each coverage.

Employer-paid coverages (non-contributory) will be effective on the eligibility date (May 1st), while voluntary (contributory) coverages will be effective on the event date plus any policy provisions (standard, first of following month, or first of coinciding/following month).

If the event date is after the end of the 30-day grace period (June 1st or later), the enrollment is considered late and may have different effective dates for each coverage.

Employer-paid coverages are never considered late and will always go back to the original eligibility date (May 1st), while voluntary coverages will be effective on the next open enrollment date for dental and vision or pending for EOI for voluntary life and disability.

QLEs

Members have 31 days to elect coverage from the event date.

If the event date is between the QLE date and the end of the 31-day window, the request is timely and coverage will be effective on the QLE date.

If the event date is 31+ days from the QLE date, the enrollment is late and will be effective on the next open enrollment period or stay pending for EOI.

​

Open enrollment

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

When the plans in Principal’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.

Open enrollment changes that are submitted more than 31 days after the OE window closes will be applied with the next year’s OE date as the effective date. For example, an OE request to add dental coverage received on January 1st, 2024 for an October 1st, 2023 renewal group would result in dental coverage added with a start date of October 1st, 2024.

Principal’s effective date calculation is based on the employee’s hire date and the group’s waiting period.

For information on special enrollment scenarios, see our guides on:

• COBRA enrollments
• Evidence of Insurability (EOI) for life, AD&D, STD, LTD, or critical illness