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.
When to send a group connection request
As soon as the group’s coverage application is finished and approved by the carrier and their carrier-specific identifier has been issued (known as the carrier_group_id in the Noyo system), you can send a group connection request.
Group connections cannot be fully completed until the carrier has finished installing all the group’s account structure and plans in their system. We will re-try requests if the carrier is not ready yet, but in some cases there may be additional authorization needed as well. A status for each group connection is available in the API response or in the Command Center (where you can also trigger a retry and amend information).
Example group connection request
You can add a new connection for an existing group or get a list of all their connection requests.
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.
While it isn’t a required field, Noyo recommends including the group broker’s FEIN whenever it is known. This will help prevent delays and further intervention in the connection process, along with keeping your integration easy to extend to additional carriers.
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 (only if using Explicit config) and link members to ensure our systems are aligned.
Dynamic config is recommended for all new Noyo integrations and makes carrier-specific config values no longer required. This page should only be used for existing Noyo integrations.
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.
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:
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:
| 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.
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.
During this time, continue to send enrollments to the carrier via your current transmission methods (file, form, etc.) Once Noyo’s integration has been approved by the carrier you can retire any existing methods of transmission.
While Noyo builds the file, you should continue to send enrollments to the carrier via your current transmission method (file, form, etc.). You should retire this method prior to Noyo’s first delivery of an approved production file to the carrier to prevent data integrity issues in the carrier’s system.
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.
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:
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:
| 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 | We are waiting to receive group setup instructions from the carrier, or waiting to receive feedback on test files from the carrier. |
carrier_authorization | We are working to obtain group information from the carrier before testing begins. |
action_required | You need to either map plans and send the group census or resolve data discrepancies shared by the carrier. |
unable_to_connect | The carrier was unable to accept this group connection. |
completed | The production file was approved and you can manage enrollment and eligibility changes through Noyo for this group. |
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. See carrier pages in Command Center for per-carrier 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.