Request a Group Connection

Tell us about your group

Connecting a group is the process of populating Noyo’s system with information about one group/carrier combination. After you submit basic information about the group, we bring further details into our system and make them available to you.

Any group you want to manage with Noyo, regardless of carrier, must be connected before you can send enrollment changes.

Group connection prerequisites

  • The group's application must be finished and their coverage approved by the carrier. This generally results in a group number or other identifier being assigned.
  • The group must be installed at the carrier, meaning they are set up in the carrier system with group-level plans and account structure in place. Noyo can support situations where no employees are enrolled yet and their first enrollments pass through our system or the employees are all already enrolled.
  • Noyo has been authorized to transmit data on behalf of the group. The process for this can vary by carrier, but generally involves the group or the broker alerting the carrier that Noyo is the responsible vendor. Further details can be found for each carrier in the Command Center.

You can connect a group via API or in the Command Center; this guide covers the API process. To connect groups over API, you need to have activated the carrier, which often requires building some special configurations for how they accept group data. Specs for each carrier are available in the Command Center.

Example group connection request

You can request a connection for a brand-new group to Noyo or add a new connection for an existing group. For an existing group, you may also want to get a list of all their connection requests.

curl -X POST 
--header "Authorization: Bearer <ACCESS_TOKEN>" 
https://fulfillment.noyo.com/api/v1/group_connections 
{ 
  "carrier_id": "c699414d-fd1c-4de4-86f0-66dfff2276c4", 
  "federal_ein": "123456789", 
  "group_data": { 
    "group_name": "Test Company", 
    "carrier_group_id": "00110011" 
  } 
}

The carrier_id field, found in many areas of the Noyo API, is a unique ID that Noyo assigns to each carrier in our network, while the carrier_group_id identifies the group in the carrier system, essentially like a group number, policy number, or master agreement number.

Unique carrier identifiers and guidance on how to find the relevant carrier_group_id is available in the Command Center on each carrier’s info page.

When your API call to create a group connection request is successful, the response will return a unique ID for the Group Connection, and a unique ID for the Group added to Noyo. We recommend storing both IDs to reference those objects, while Noyo works in the background to ensure we have access to the group.

You can pipe all your group connection requests into your own internal tools or manage them in our Command Center.

Connecting groups to Sync carriers

After you send a group connection request involving a Sync carrier, we query the carrier’s system directly for authorization and fetch any account structure, plan, or enrollment data that exists. (Enrollment data will only be available for groups who have existing coverage with the carrier.) We structure and normalize this data and make it available to you through our GET endpoints. Most group connections with Sync carriers only take a few minutes to complete as long as the prerequisites are in place.

Next you’ll map plans and account structures and link members to ensure our systems are aligned.

📘

You can use Noyo’s account structure, plan, and enrollment data to create records for brand-new groups in your own system automatically, rather than waiting to collect data from a group admin or broker.

For groups already set up in your system, Noyo makes it possible to review and compare the carrier data with your existing view of the group. We highly recommend doing this before sending enrollment changes to avoid creating discrepancies.

The group connection flow for Sync carriers, with statuses available at each step

The group connection flow for Sync carriers, with statuses available at each step

Check the connection status

While a group connection request is in process, you can periodically poll for any updates to the Group Connection using the ID returned when the group connection was created. Here is an example request and response payload for the Get Single Group Connection endpoint:

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/group_connections/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1

Sample response:

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
    "created": 1557329939,
    "modified": 1557332412,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "carrier_id": "c699414d-fd1c-4de4-86f0-66dfff2276c4",
    "group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
    "request_type": "initial",
    "status": "completed",
    "completed": 1557330213,
    "group_data": {
        "group_name": "Test Company",
        "carrier_group_id": "00110011"
    }
}

When Noyo has finished processing all available data for the group and created the new records in our system, the status of the Group Connection will be updated to completed. At this point, you can use our API endpoints to access all the data we have about the group.

Group connections will move through several different statuses, as illustrated in the diagram above. Here’s what those statuses mean:

KeyDescription
createdThis status is the result of the initial submission (POST). We have not yet verified the current state of the carrier’s system.
processingWe are communicating the group connection to the carrier involved.
noyo_reviewNoyo is actively resolving an issue with the group connection; no action is needed from you.
waiting_on_carrierThe group connection has been submitted and the carrier is processing it.
carrier_authorizationThere was an authorization problem when pulling group data from a carrier. It may require you to reach out to the carrier to resolve.
action_requiredAction from you is required for successful processing. Notes are listed in the setup_result field on the group connection object.
unable_to_connectThe carrier was unable to install this group connection. Notes are listed in the setup_result field on the group connection object.
completedThe group connection has been completed and Noyo now has the ability to manage enrollment and eligibility changes for the specific group that is installed on the carrier’s system

Setup Results

The setup_result allows us to pass along information that may be helpful in troubleshooting a failed group connection request. Its structure will depend on the group connection's status: if the request is in noyo_review, action_required, waiting_on_carrier, or unable_to_connect , the setup result may contain an error string that gives further details about the specific issue involved.

For other statuses, the setup_result will be empty.

Connecting groups to Send carriers

After you send a group connection request involving a Send carrier, our team reaches out to that carrier for the group’s account structure. It generally takes 1-2 weeks for the account structure to be received and loaded into our system, which makes it available through our endpoints; our team will inform you when this data is available so you can map plans and account structures and submit census data.

We do not pull enrollment data from Send carriers during the group connection process. This means you will need to create the group’s employees and dependents in our system by sending an initial “census” via a series of member snapshots, with a custom_individual_id included for each member. The success responses will contain each person’s Noyo ID, which you should include in future snapshots along with your custom ID. All 4xx errors will need to be resolved at this time to ensure that all enrollments are present and the Noyo team can build the file successfully.

👍

Visit the Developer tab in the Command Center for a list of errors that can be sorted by path.

Once you send the census snapshots, we can populate the file with real data and complete the testing process according to the carrier’s specifications. This typically takes about 6 weeks with a responsive carrier. Our team will reach out to you with any discrepancies the carrier identifies; to resolve them, you’ll need to update/correct the bad data in your system (which may involve reaching out to the group admin) and send us new member snapshots, and then communicate the changes to the carrier directly as well. This process may need to be repeated until most discrepancies are resolved.

The carrier will officially approve the file when they determine that the structure is correct and the member data is sufficiently accurate. At this point, the group connection is marked complete in our system and new enrollments and changes can be sent to Noyo on an ongoing basis. We process these snapshots and identify the changes that should be sent on the next file (check the carrier’s page in the Command Center for specifics on file delivery cadence). After the group connection is complete, you don't need to communicate changes directly to the carrier anymore.

The group connection flow for Send carriers, with statuses available at each step

The group connection flow for Send carriers, with statuses available at each step

Check the connection status

While a group connection request is in process, you can periodically poll for any updates to the Group Connection using the ID returned when the group connection was created. Here is an example request and response payload for the Get Single Group Connection endpoint:

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/group_connections/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1

Sample response:

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
    "created": 1557329939,
    "modified": 1557332412,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "carrier_id": "c699414d-fd1c-4de4-86f0-66dfff2276c4",
    "group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
    "request_type": "initial",
    "status": "completed",
    "completed": 1557330213,
    "group_data": {
        "group_name": "Test Company",
        "carrier_group_id": "00110011"
    }
}

When Noyo has sent the first production file, the status of the Group Connection will be updated to completed. At this point, you can use our API endpoints to access the most recent data you’ve sent us about the group.

Group connections will move through several different statuses, as illustrated in the diagram above. The status values are the same for all group connections, but the meanings vary slightly for Send connections:

KeyDescription
createdThis status is the result of the initial submission (POST). We have not yet verified the current state of the carrier’s system.
processingWe are communicating the group connection to the carrier involved.
noyo_reviewNoyo is actively resolving an issue with the group connection; no action is needed from you.
waiting_on_carrierWe are waiting to receive group setup instructions from the carrier, or waiting to receive feedback on test files from the carrier.
carrier_authorizationWe are working to obtain group information from the carrier before testing begins.
action_requiredYou need to either map plans and send the group census or resolve data discrepancies shared by the carrier.
unable_to_connectThe carrier was unable to accept this group connection.
completedThe production file was approved and you can manage enrollment and eligibility changes through Noyo for this group.

Group connection errors

Error NameResponse Status CodeDescription
Duplicate409Submitting a duplicate group connection (identical carrier_id and carrier_group_id as another group connection) will result in a 409 conflict error.
Missing Fields422If any required fields are missing, the request will result in a 422.
Carrier Group ID Format422Submitting a carrier_group_id that violates carrier-specific formatting will result in a 422 error. Ask Noyo for specifics on different carrier group ID formats.

Retrying a group connection request

If a group connection request has gone through its retry attempts and is in an unable_to_connect state, you can retry the group connection later through this endpoint. When you retry a group connection, you will have the option to update the unique identifier for the group (carrier_group_id).

Retrying a group connection keeps the id that was previously used to identify the group connection, and sends off the same request with any updated information to the carrier. This retry will update the status of the group connection to processing.

Ending a group connection

It's important to disconnect groups from Noyo if you are no longer managing them. Learn how.


What’s Next

Get Noyo's group data connected to your own