Request a Group Connection
Tell us about your group
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.
Key | Description |
---|---|
created | This status is the result of the initial submission (POST). We have not yet verified the current state of the carrier’s system. |
processing | We are communicating the group connection to the carrier involved. |
noyo_review | Noyo is actively resolving an issue with the group connection; no action is needed from you. |
waiting_on_carrier | The group connection has been submitted and the carrier is processing it. |
carrier_authorization | There was an authorization problem when pulling group data from a carrier. It may require you to reach out to the carrier to resolve. |
action_required | Action from you is required for successful processing. Notes are listed in the setup_result field on the group connection object. |
unable_to_connect | The carrier was unable to install this group connection. Notes are listed in the setup_result field on the group connection object. |
completed | The 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.
Group connection errors
Error Name | Response Status Code | Description |
---|---|---|
Duplicate | 409 | Submitting a duplicate group connection (identical carrier_id and carrier_group_id as another group connection) will result in a 409 conflict error. |
Missing Fields | 422 | If any required fields are missing, the request will result in a 422. |
Carrier Group ID Format | 422 | Submitting 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. |
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.
Updated 6 days ago