Request a Group Connection

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

Start sending group connection requests after you've activated the target carrier; i.e., you've finished building to their individual specifications. Specs for each carrier are found in the Command Center.

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 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",
    "broker_federal_ein": "123123123"
  } 
}

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.

🚧

Include broker FEIN whenever possible

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 and link members to ensure our systems are aligned.

📘

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:

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",
        "broker_federal_ein": "123123123"
    }
}

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:

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.

🚧

Retiring your existing data exchange method

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:

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",
        "broker_federal_ein": "123123123"
    }
}

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:

Group connection errors

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.