Request a Group Connection

Connecting a group is the process of telling Noyo how to find a single group in a single carrier's system. Once we have authorization to access that group's data, we load it into our platform, where it becomes available to you.

Group connection prerequisites

• You need to have activated the target carrier for the group. You will activate carriers during onboarding when our team shares specs for each carrier in our network.
• The group's application must be finished and their coverage is 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.
• The carrier must know that your ben-admin platform is associated with the group and has granted Noyo permission to access group data on your behalf.

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.

We will share our unique carrier identifiers and provide guidance on how to find the relevant carrier_group_id for each carrier partner during your integration process.

When the 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 and then starts our group sync process.

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

Check the group connection status

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 they pass through Noyo's system and are sent to the carrier.

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.

Group connection errors

This diagram shows the potential paths for a group connection:

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.

After a group is connected

For some groups that are brand new to your system and may require a long setup process to collect data, you can use Noyo’s API to pull group and member details and create your records automatically, based on what the carrier has on file.

For other 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.

Ending a group connection

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