Once we have full authorization and a group connection is complete, any member snapshot you send for that group/carrier pair will be fulfilled with the carrier via Noyo.
Why Connect a Group?
You should connect a group when you’re ready to activate fulfillment through Noyo. This can also mean switching from an existing fulfillment method. Our process supports groups with no employees enrolled yet, as well as groups where employees are already enrolled.The Connection Process by Tier
The path to a completed connection status differs depending on the carrier’s tier. Premier Tier For Premier connections, we query the carrier’s system directly for authorization and fetch all available account structure, plan, and enrollment data. We then pull this data into our system, do an initial data comparison, and make it available to you via our GET endpoints. Once the connection status is completed, you can send member snapshots for real-time fulfillment and round-trip confirmation. Advanced and Standard Tiers For these connections, the process is not fully complete until an initial “census” has been sent via member snapshots. This is necessary to create the group’s employees and dependents in our system, as we do not pull in member data from these tiers. This also allows our team to build and test the file with the carrier. The connection is only marked completed after the carrier has officially approved the file. You should continue to send enrollments to the carrier via your current method until the Noyo integration is approved.Requesting a Group Connection
Connecting a group is the process of populating Noyo’s system with information about one group/carrier combination. As soon as the group’s coverage application is approved by the carrier and their carrier-specific identifier (carrier_group_id) has been issued, you can send a group connection request. Requesting a Connection via API You can send a new connection for an existing group or create one from scratch. The carrier_id is a unique ID Noyo assigns to each carrier in our network, while the carrier_group_id identifies the group in the carrier system (like a group number or policy number).Example group connection request You can add a new connection for an existing group or get a list of all their connection requests.Request
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.
Include all optional fields whenever possible
Not all fields in a connection request are required. We still recommend providing as much information as possible every time - it helps avoid roadblocks and reduces average connection times.
Not all fields in a connection request are required. We still recommend providing as much information as possible every time - it helps avoid roadblocks and reduces average connection times.
Connecting groups to Premier carriers
After you send a group connection request involving a Premier 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 Premier 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.
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:Request
Response
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
Thesetup_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 with Advanced & Standard carriers
After you send a group connection request involving a Standard or Advanced 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 Advanced/Standard 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 acustom_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
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.
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:Request
Response
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 anunable_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.