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.

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.

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.

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.


What’s Next

Get Noyo's group data connected to your own