Noyo Group Benefits API
Scroll down for code samples, example requests and responses.
The Noyo group benefits API enables benefits administration platforms to seamlessly manage group benefits policies with many insurance carriers simultaneously. Noyo automates administration across the entire policy lifecycle, from initial group installation through setup, ongoing eligibility management, and renewal.
Get started by installing or connecting a group:
Installation is for groups that do not have existing coverage with a carrier. You’ll use Noyo’s endpoints to fill out an application, submit relevant documents, and track whether the carrier has installed the group in their system.
Connecting a group is necessary for groups that already exist at the carrier. Once a group is successfully connected, you can begin sending policy management requests through Noyo.
Notes
In the field lists in this document...
* designates that field is required
ˢ designates that field is situationally required
All datetimes can be assumed to be represented in UTC timezone, unless otherwise noted. Datetimes expressed as an integer value are relative to the Unix epoch.
How Noyo’s API is unique
You may notice that many service endpoints do not support methods to directly create or update particular objects (member transactions, individual enrollments, groups, etc.). Instead of this approach, Noyo provides interfaces that allow you to request that actions be taken, such as a member request or a group connection. These requests are routed through Noyo’s enrollment rules and the carrier system, which can in turn create or update read-only objects. This separation between requests and results ensures that requested actions are routed through the appropriate channels and result in the appropriate action; it also allows you to discover the status of a given request.
Authentication
Code Sample
curl -X POST
--header "Content-Type: application/json"
--header "Authorization: Basic <Base64Encode(<CLIENT_ID>:<CLIENT_SECRET>)>"
--data '{"grant_type": "client_credentials"}'
https://accounts.noyo.com/auth/public/token
Example Response
{
"access_token": "<ACCESS_TOKEN>",
"expires_in": 864000,
"token_type": "Bearer"
}
Each customer account has a unique pair of API credentials. Contact Noyo support to receive an CLIENT_ID, CLIENT_SECRET pair as part the initial onboarding.
Getting a Token
In order to make API calls to Noyo's API you just generate a temporary access token (valid for 10 minutes) by calling https://accounts.noyo.com/auth/public/token using your CLIENT_ID and CLIENT_SECRET as the username/password combination in a Basic Authentication header.
Calling the API
After generating the token using the instructions above, include the ACCESS_TOKEN in the Authorization header for each request: Authorization: Bearer <ACCESS_TOKEN>.
Sandbox
Noyo provides a sandbox environment for our APIs to aid the development process. The API of the sandbox is identical to that of the live services. However, it does not carry out your actions against insurance carrier systems. This will allow you to develop and test your Noyo integration before going live. You can use your sandbox API credentials to generate an access token from https://accounts.noyo.com/auth/public/token. Just follow the authentication instructions!
After you have generated your access token you can access the sandbox API for each service by using these domains:
Group Installation: https://group-installation-sandbox.noyo.com
Fulfillment: https://fulfillment-sandbox.noyo.com
Member Requests on Sandbox
A member request created on the sandbox API will initially return in the processing status. Within a random period of time after submission, up to 15 seconds, it will return in the completed status. See member request statuses for more information.
Renewal Decisions on Sandbox
A renewal decision created on the sandbox API will initially return in the submitted status. Within a random period of time, up to 15 seconds, it will return with an updated status, based on the scenarios below. This will simulate the process of a renewal decision being compared against carrier data. See renewal decision statuses for more information.
Renewal decision scenarios
Different renewal decision scenarios can be captured on the sandbox by using the renewal date's day of the month as a special value.
By supplying a renewal date with a day of the month of the following values, you will trigger the following scenarios:
| Renewal Date - Day of Month | Status | Issue |
|---|---|---|
| 1 | ready | |
| 2 | not_ready | Missing Coverage |
| 3 | not_ready | Unexpected Coverage |
| 4 | not_ready | Unexpected coverage end date. Coverage still active, but carrier end date is before renewal date. |
| 5 | not_ready | Unexpected coverage end date. Coverage dropped, but carrier end date is after renewal date. |
| 6 | not_ready | Unexpected open enrollment dates |
| 7 | not_ready | Inconsistent plan quantities |
Pagination
Code Sample
curl -X GET
--header "Content-Type: application/json"
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups?page_size=5&offset=5
Example Response
{
"meta": {
"offset": 5,
"page_num": 2,
"page_size": 5,
"total_records": 60
},
"response": [
{
"id": "049c6ac3-3cf2-4d99-b781-aaa9aa846cb2",
"version": "0dce45a0-089c-470a-a15b-58080159d407",
"created": 1557862286,
"modified": 1557862286,
"organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
"name": "Company 1",
"sic_code": "2121"
},
{
"id": "06108fa4-ce4e-47d9-bb2f-8aec0553f9e5",
"version": "0e418c78-a9df-4fd5-9d32-639015eff637",
"created": 1558451441,
"modified": 1558451441,
"organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
"name": "Company 2",
"sic_code": "2121"
},
{
"id": "0bbb8ebb-26a8-4724-99d3-5c76c198be0a",
"version": "84f253a4-ce07-4601-ac13-75b410c4a94b",
"created": 1557862304,
"modified": 1557862304,
"organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
"name": "Company 3",
"sic_code": "2121"
},
{
"id": "0dc7c14f-4184-4a35-ab67-ff127bfd7bc9",
"version": "ff9d3603-45a0-46f2-b035-96fa777255b3",
"created": 1557868278,
"modified": 1557868278,
"organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
"name": "Company 4",
"sic_code": "2121"
},
{
"id": "12a2f910-8959-4076-9907-2050945da309",
"version": "db3cf8d5-185a-49ff-80e3-ee3afe56f935",
"created": 1557329939,
"modified": 1557329939,
"organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
"name": "Company 5",
"sic_code": "2121"
}
]
}
All resources that support bulk fetching a "list" of objects share a common structure and take the
optional arguments page_size and offset.
Query Parameters
page_size |
Number of records returned in the list, defaults to 20, must be at least 5, cannot exceed 100 |
offset |
The entry in the list at which to begin returning results, defaults to 0 |
Paginated Result
meta |
|
response |
Array of records in the list, structure will vary by endpoint. |
Changes Over Time
Several of the Noyo models track data elements that change over time. For example, a group plan may only be available for one enrollment year but then it could be discontinued, or a member might enroll in the same life plan for multiple years but their coverage volume could change after each open enrollment period.
The Noyo API endpoints allow callers to query for these models with an optional target effective_date. This will allow you to easily answer questions like "What was the status of this user's enrollment one month ago?" or "What volume of coverage did the member elect last year?". The group carrier configuration, group enrollment, group plan, and individual enrollment models all support this behavior.
The API will return our best approximation of the status of a record as-of the requested effective_date, given that we may not be able to reconstruct the complete history of a record for all carriers. The default behavior when no effective_date is provided is to return the state of the record as-of today.
Example: Individual Enrollments
Suppose you sent Noyo a member request to enroll an employee in coverage and their individual enrollment was created with an effective_start_date for coverage on 7/1/2020.
Querying with an effective_date prior to the effective_start_date
Code Sample
curl -X GET
--header "Content-Type: application/json"
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/individual_enrollments/ac96373c-fcb2-4cb5-af1f-52d2afeace01?effective_date=2020-06-15
Example Response
{
"id": "ac96373c-fcb2-4cb5-af1f-52d2afeace01",
"version": "fe8c33aa-2721-4097-9695-63512f8ac90a",
"group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
"line_of_coverage": "medical",
"status": "pending",
"individual_type": "employee",
"individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
"enroll_data": {},
"effective_start_date": "2020-07-01",
"effective_end_date": "2021-07-01",
"individual_enrollment_configuration": {},
"created": 1592141191,
"modified": 1592141191
}
With an effective_date prior to the resource's effective_start_date, the individual enrollment in the response should have a pending status. It's also possible that no record will be returned if Noyo did not have any record of this enrollment prior to the effective_start_date, as may be the case in a broker of record change.
Querying with an effective_date after the effective_start_date
Code Sample
curl -X GET
--header "Content-Type: application/json"
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/individual_enrollments/ac96373c-fcb2-4cb5-af1f-52d2afeace01?effective_date=2020-07-15
Example Response
{
"id": "ac96373c-fcb2-4cb5-af1f-52d2afeace01",
"version": "fe8c33aa-2721-4097-9695-63512f8ac90a",
"group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
"line_of_coverage": "medical",
"status": "active",
"individual_type": "employee",
"individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
"enroll_data": {},
"effective_start_date": "2020-07-01",
"effective_end_date": "2021-07-01",
"individual_enrollment_configuration": {},
"created": 1592141191,
"modified": 1592141191
}
After the member request is completed and the member is confirmed active on coverage, querying for the individual enrollment with an effective_date after the resource's effective_start_date should return a status of active. As long as we have not received a termination or a QLE request to remove this coverage, you will find that the response returns an active status even for dates far in the future.
Querying with an effective_date after the effective_end_date
Code Sample
curl -X GET
--header "Content-Type: application/json"
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/individual_enrollments/ac96373c-fcb2-4cb5-af1f-52d2afeace01?effective_date=2020-11-01
Example Response
{
"id": "ac96373c-fcb2-4cb5-af1f-52d2afeace01",
"version": "fe8c33aa-2721-4097-9695-63512f8ac90a",
"group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
"line_of_coverage": "medical",
"status": "terminated",
"individual_type": "employee",
"individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
"enroll_data": {},
"effective_start_date": "2020-07-01",
"effective_end_date": "2020-09-30",
"individual_enrollment_configuration": {},
"created": 1592141191,
"modified": 1592181928
}
Suppose you later send Noyo a termination member request for this employee and their individual enrollment is updated with a coverage effective_end_date of 9/30/2020.
After the member request is completed and the member coverage is confirmed to be terminated on 9/30/2020, querying for the individual enrollment with an effective_date after the resource's effective_end_date should return a status of terminated.
OpenAPI Specs
Noyo now offers OpenAPI interfaces of our APIs. You may use the links below to check out the JSON files for Noyo services. These may be used to pull into tools to understand the API interface better, build API clients, etc.
Integration Guide
Group Installation Flow
The following diagram illustrates the typical flow of creating an application for a group and sending it to one or more carriers:
- Create the group.
- Configure the group (e.g. add locations, add contacts).
- Create one or more applications (one per carrier).
- Add lines of coverage and plans to an application.
- Create employees and dependents for a group.
- Associate employees' and dependents' enrollment choices with plans.
- Create an application document to create space for a file upload.
- Upload the application document.
- Submit the application.
Mapping for Enrollment Management
The Noyo API is able to provide a level of correctness and visibility by working based off unique identifiers for things like Plans, Employees, and Dependents. This ensures that requests coming in from the API can go through extensive validation to ensure the correct actions are taken with each carrier. From an integration standpoint this requires some amount of mapping between the entities in the Noyo system and the entities in your system. This guide serves as a blueprint for how you can go about that mapping process and then proceed to making ongoing requests to the API.
Two Mapping Flows
There are two types of mapping flows with the Noyo API depending on whether the group has existing coverage with the insurance carrier or is getting enrolled for the very first time with that carrier.
Existing Group Setup
In this case the Noyo API is populated with information about the group's plans, employees, dependents and enrollments already (pulled directly from the carrier system). You are responsible for mapping these entities and their unique IDs to the corresponding entities in your system.
You should create a function / routine / process / etc. that for a given group can perform the following operations:
New Group Setup
The Noyo API is populated with information about the group's plans, but you are responsible for creating employees and dependents and instructing what plans they should be enrolled in.
You should create a function / routine / process / etc. that for a given group can perform the following operations:
Mapping Groups
You can query a list of all groups in the API using the Get Groups endpoint. Remember you can use the pagination query parameters to go through more groups at one time. You should be able to match up the group using the following fields:
| Field | Description |
|---|---|
name |
Always present |
dba_name |
Optional, Doing Business As name |
Alternatively, in order to identify a group by a carrier-specific ID, use the group list endpoint and query using a carrier_id and carrier_group_id combination. This may be a helpful mapping if these are IDs you store. See our carrier specs for what carrier-specific ID is used for each carrier.
Mapping Employees
You can query a list of all employees within a group using the Filtering Employees in a Group endpoint. You can optionally specify filters in the query parameters for first_name, last_name, and date_of_birth. You should be able to match up the employee using the following fields:
| Field | Description |
|---|---|
person.first_name |
Always present, make sure to map agnostic of letter casing |
person.last_name |
Always present, make sure to map agnostic of letter casing |
person.date_of_birth |
Always present, always in the format YYYY-MM-DD |
person.ssn |
Optional, not all carriers store this in their system |
Mapping Dependents
Once you have mapped the employee you can query the dependents that belong to that employee with the Get Dependents endpoint. You should be able to match up the dependents using the following fields:
| Field | Description |
|---|---|
person.first_name |
Always present, make sure to map agnostic of letter casing |
person.last_name |
Always present, make sure to map agnostic of letter casing |
person.date_of_birth |
Always present, always in the format YYYY-MM-DD |
person.ssn |
Optional, not all carriers store this in their system |
relationship |
Always present |
Mapping Plans
Map a group's plans using the group plans endpoint. Plans can be matched by some combination of line of coverage, name, and other attributes included in the API response. The API will return plans associated with a group enrollment for its carrier and effective dates. Group enrollment data should also be mapped to your data, especially so that correct open enrollment dates can be recorded. A common hierarchy of group enrollments and group plans looks like this:
Enrolling During New Group Setup
During the New Group Setup process, the Employees and Dependents will not yet exist and it will be your responsibility to create them using the Create Employee and Create Dependent endpoints. After you make the create requests you should save the IDs of the created employees and dependents into your system.
After you have created these you can send an Open Enrollment Member Request for each employee which includes information about what plan(s) the employee and their dependents would like to enroll in.
Group Structure Mapping
Noyo provides a tool within the dashboard for group structure and plan name mapping. To use the Group Structure Mapping tool for a group already in the Noyo system, just submit the group’s account structure information with the Account Structure object. After the account structure is submitted and the group is successfully connected to a new carrier, users can access the Group Structure Mapping tool and begin creating rules to classify members and plans.
Ongoing Member Requests
After the mapping process completes for each a group (either through the existing or new group setup flow) you will be able to start making ongoing Member Requests to the API. This should be very straightforward after the mapping process is completed because the payloads consist largely of IDs and the validation will prevent you from sending incorrect or incomplete data to the API. More details on creating API calls for each Member Request can be found here:
Group Installation
In our group installation service, we will support the initial application flow (creating and configuring a group, creating employees and dependents, adding lines of coverage, and plans) document management, (sending the list of required documents and associating the completed documents with the application), and application submission and confirmation.
Note: Groups successfully installed at the carrier through Noyo’s API are automatically available for enrollment management; no additional connection is needed.
Groups
Create a group
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups
Body Parameter
{
"name": "Metgenics",
"sic_code": "1000",
"federal_ein": "98-7654321",
"business_details": {
"company_description": "Metal mining for the common person",
"date_established": "2020-01-01",
"employer_type": "private_sector",
"entity_type": "s_corp"
},
"insurance_details": {
"is_erisa_compliant": false,
"is_erisa_subject": false
}
}
Example Response
{
"id": "97c1bce3-0dde-4823-bea5-4f3f3af1d4ed",
"version": "44b130ee-3b71-4ab3-8b02-94d1aca55922",
"organization_id": "76448284-fef2-43b3-a1ba-adac62bea52c",
"name": "Metgenics",
"sic_code": "1000",
"federal_ein": "98-7654321",
"business_details": {
"company_description": "Metal mining for the common person",
"date_established": "2020-01-01",
"employer_type": "private_sector",
"entity_type": "s_corp"
},
"insurance_details": {
"is_erisa_compliant": false,
"is_erisa_subject": false
},
"created": 1628617987,
"modified": 1628617987
}
In this step you’ll pass basic information about the group, such as their name, SIC code, and EIN. You can then move on to further configure the group, associate this group with one or more applications, and add employees and dependents to that group.
Request Body
name* |
string | Name of the group/company |
dba_name |
string | DBA name for the company, if applicable |
sic_code |
string | SIC Code for the group/company |
federal_ein |
string | Federal Employer Identification Number for the group/company |
business_details |
object |
|
insurance_details |
object |
|
organization_id |
uuid | Unique identifier of the platform or broker organization in the Noyo system |
Create Group Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
organization_id* |
uuid | Unique identifier of the platform or broker organization in the Noyo system |
name* |
string | Name of the group/company |
dba_name |
string | DBA name for the company, if applicable |
sic_code |
string | SIC Code for the group/company |
federal_ein |
string | Federal Employer Identification Number for the group/company |
business_details |
object |
|
insurance_details |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Getting all groups
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "97c1bce3-0dde-4823-bea5-4f3f3af1d4ed",
"version": "44b130ee-3b71-4ab3-8b02-94d1aca55922",
"organization_id": "76448284-fef2-43b3-a1ba-adac62bea52c",
"name": "Metgenics",
"sic_code": "1000",
"federal_ein": "98-7654321",
"business_details": {
"company_description": "Metal mining for the common person",
"date_established": "2020-01-01",
"employer_type": "private_sector",
"entity_type": "s_corp"
},
"insurance_details": {
"is_erisa_compliant": false,
"is_erisa_subject": false
},
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all groups
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
group_ids |
The comma separated list of group_ids to filter by |
Get all groups response
meta* |
object |
|
response* |
array |
|
Getting a single group
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/97c1bce3-0dde-4823-bea5-4f3f3af1d4ed
Example Response
{
"id": "97c1bce3-0dde-4823-bea5-4f3f3af1d4ed",
"version": "44b130ee-3b71-4ab3-8b02-94d1aca55922",
"organization_id": "76448284-fef2-43b3-a1ba-adac62bea52c",
"name": "Metgenics",
"sic_code": "1000",
"federal_ein": "98-7654321",
"business_details": {
"company_description": "Metal mining for the common person",
"date_established": "2020-01-01",
"employer_type": "private_sector",
"entity_type": "s_corp"
},
"insurance_details": {
"is_erisa_compliant": false,
"is_erisa_subject": false
},
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single group based on the ID provided.
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Get a single group response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
organization_id* |
uuid | Unique identifier of the platform or broker organization in the Noyo system |
name* |
string | Name of the group/company |
dba_name |
string | DBA name for the company, if applicable |
sic_code |
string | SIC Code for the group/company |
federal_ein |
string | Federal Employer Identification Number for the group/company |
business_details |
object |
|
insurance_details |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit a group
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/8a4b1f15-d4d8-4139-8c3f-8aeb6050841e
Body Parameter
{
"name": "Metvio"
}
Example Response
{
"id": "97c1bce3-0dde-4823-bea5-4f3f3af1d4ed",
"version": "2f105731-7057-4aa8-a073-ccbb4ed6d8d3",
"organization_id": "76448284-fef2-43b3-a1ba-adac62bea52c",
"name": "Metvio",
"sic_code": "1000",
"federal_ein": "98-7654321",
"business_details": {
"company_description": "Metal mining for the common person",
"date_established": "2020-01-01",
"employer_type": "private_sector",
"entity_type": "s_corp"
},
"insurance_details": {
"is_erisa_compliant": false,
"is_erisa_subject": false
},
"created": 1628617987,
"modified": 1628617990
}
Edit a group based on the ID provided. The version parameter must match the latest group version.
Path Parameters
group_id |
The unique identifier of the group in Noyo |
version |
The current version identifier of the group |
Request Body
name |
string | Name of the group/company |
dba_name |
string | DBA name for the company, if applicable |
sic_code |
string | SIC Code for the group/company |
federal_ein |
string | Federal Employer Identification Number for the group/company |
business_details |
object |
|
insurance_details |
object |
|
Edit Group Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
organization_id* |
uuid | Unique identifier of the platform or broker organization in the Noyo system |
name* |
string | Name of the group/company |
dba_name |
string | DBA name for the company, if applicable |
sic_code |
string | SIC Code for the group/company |
federal_ein |
string | Federal Employer Identification Number for the group/company |
business_details |
object |
|
insurance_details |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Contacts
Create a contact
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/40ed8d7f-3698-4d04-9b28-b2fb3532f5d7/contacts
Body Parameter
{
"first_name": "Joanee",
"last_name": "Schmidt",
"title": "CFO",
"email": "joanee@company.com",
"phone_number": "5554443322",
"fax_number": "5551113322",
"types": [
"billing",
"executive"
],
"primary_contact": true
}
Example Response
{
"id": "e013e4b9-a2e0-4934-8d3c-fab67d9aa03f",
"version": "8bfd86e8-dee2-4e96-b1a5-3dc8745fd7cf",
"group_id": "40ed8d7f-3698-4d04-9b28-b2fb3532f5d7",
"first_name": "Joanee",
"last_name": "Schmidt",
"title": "CFO",
"email": "joanee@company.com",
"phone_number": "5554443322",
"fax_number": "5551113322",
"types": [
"billing",
"executive"
],
"primary_contact": true,
"created": 1628617987,
"modified": 1628617987
}
Create a new contact for a group
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Request Body
first_name* |
string | First name of the group contact |
last_name* |
string | Last name of the group contact |
title |
string | Job title of the group contact |
email* |
string | Work email address of the group contact |
phone_number |
string | Work phone number of the group contact in E.164 format |
fax_number |
string | Fax number of the group contact in E.164 format |
types* |
array | List of contact types for the group contact. One of: billing, company, executive, online |
primary_contact |
boolean | True if contact is the primary contact for the group |
Create Contact Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
first_name |
string | First name of the group contact |
last_name |
string | Last name of the group contact |
title* |
string | Job title of the group contact |
email* |
string | Work email address of the group contact |
phone_number* |
string | Work phone number of the group contact in E.164 format |
fax_number* |
string | Fax number of the group contact in E.164 format |
types* |
array | List of contact types for the group contact. One of: billing, company, executive, online |
primary_contact* |
boolean | True if contact is the primary contact for the group |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Get all group contacts
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "e013e4b9-a2e0-4934-8d3c-fab67d9aa03f",
"version": "8bfd86e8-dee2-4e96-b1a5-3dc8745fd7cf",
"group_id": "40ed8d7f-3698-4d04-9b28-b2fb3532f5d7",
"first_name": "Joanee",
"last_name": "Schmidt",
"title": "CFO",
"email": "joanee@company.com",
"phone_number": "5554443322",
"types": [
"billing",
"executive"
],
"primary_contact": true,
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all contacts for a given group
Path Parameters
group_id |
The unique identifier of the group for which you would like to view contacts |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get all contacts response
meta* |
object |
|
response* |
array |
|
Get a single group contact
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/40ed8d7f-3698-4d04-9b28-b2fb3532f5d7/contacts/e013e4b9-a2e0-4934-8d3c-fab67d9aa03f
Example Response
{
"id": "e013e4b9-a2e0-4934-8d3c-fab67d9aa03f",
"version": "8bfd86e8-dee2-4e96-b1a5-3dc8745fd7cf",
"group_id": "40ed8d7f-3698-4d04-9b28-b2fb3532f5d7",
"first_name": "Joanee",
"last_name": "Schmidt",
"title": "CFO",
"email": "joanee@company.com",
"phone_number": "5554443322",
"fax_number": "55511133322",
"types": [
"billing",
"executive"
],
"primary_contact": true,
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single contact based on the ID provided.
Path Parameters
group_id |
The unique identifier of the group in Noyo |
contact_id |
The unique identifier of the contact in Noyo |
Get a single group contact response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
first_name |
string | First name of the group contact |
last_name |
string | Last name of the group contact |
title* |
string | Job title of the group contact |
email* |
string | Work email address of the group contact |
phone_number* |
string | Work phone number of the group contact in E.164 format |
fax_number* |
string | Fax number of the group contact in E.164 format |
types* |
array | List of contact types for the group contact. One of: billing, company, executive, online |
primary_contact* |
boolean | True if contact is the primary contact for the group |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit a contact
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/4632c3f7-b120-4a37-9b10-5911098d40ee
Body Parameter
{
"phone_number": "+15555551212"
}
Example Response
{
"id": "e013e4b9-a2e0-4934-8d3c-fab67d9aa03f",
"version": "dbc86ab1-f731-4aee-97e8-857c7a19107a",
"group_id": "40ed8d7f-3698-4d04-9b28-b2fb3532f5d7",
"first_name": "Joanee",
"last_name": "Schmidt",
"title": "CFO",
"email": "joanee@company.com",
"phone_number": "+15555551212",
"fax_number": "55511133322",
"types": [
"billing",
"executive"
],
"primary_contact": true,
"created": 1628617987,
"modified": 1628617990
}
Edit and existing contact for a group
Path Parameters
group_id |
The unique identifier of the group in Noyo |
contact_id |
The unique identifier of the contact in Noyo |
version |
The current version identifier of the contact |
Request Body
first_name |
string | First name of the group contact |
last_name |
string | Last name of the group contact |
title |
string | Job title of the group contact |
email |
string | Work email address of the group contact |
phone_number |
string | Work phone number of the group contact in E.164 format |
fax_number |
string | Fax number of the group contact in E.164 format |
types |
array | List of contact types for the group contact. One of: billing, company, executive, online |
primary_contact |
boolean | True if contact is the primary contact for the group |
Edit Contact Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
first_name |
string | First name of the group contact |
last_name |
string | Last name of the group contact |
title* |
string | Job title of the group contact |
email* |
string | Work email address of the group contact |
phone_number* |
string | Work phone number of the group contact in E.164 format |
fax_number* |
string | Fax number of the group contact in E.164 format |
types* |
array | List of contact types for the group contact. One of: billing, company, executive, online |
primary_contact* |
boolean | True if contact is the primary contact for the group |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Locations
Create a location
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations
Body Parameter
{
"address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Test Ln",
"zip_code": "94107"
},
"primary_location": true,
"billing_location": true
}
Example Response
{
"id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"primary_location": true,
"billing_location": true,
"address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Test Ln",
"zip_code": "94107"
},
"created": 1628617987,
"modified": 1628617987
}
Create a new location for a group
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Request Body
display_name* |
string | Display name for the group location |
address* |
object |
|
primary_location* |
boolean | Boolean field to determine whether the group location should be used as the primary group location |
billing_location* |
boolean | Boolean field to determine whether the group location should be used as the billing group location |
Create Location Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
display_name* |
string | Display name for the group location |
primary_location* |
boolean | Boolean field to determine whether the group location should be used as the primary group location |
billing_location* |
boolean | Boolean field to determine whether the group location should be used as the billing group location |
address* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Get all group locations
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"primary_location": true,
"billing_location": true,
"address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Test Ln",
"zip_code": "94107"
},
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all locations for a given group
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get all locations response
meta* |
object |
|
response* |
array |
|
Get a single location
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations/bd957820-4652-4ee7-8a3a-6413df21e28d
Example Response
{
"id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"primary_location": true,
"billing_location": true,
"address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Test Ln",
"zip_code": "94107"
},
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single location based on the ID provided.
Path Parameters
group_id |
The unique identifier of the group in Noyo |
location_id |
The unique identifier of the location in Noyo |
Get a single group location response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
display_name* |
string | Display name for the group location |
primary_location* |
boolean | Boolean field to determine whether the group location should be used as the primary group location |
billing_location* |
boolean | Boolean field to determine whether the group location should be used as the billing group location |
address* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit a location
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations/bd957820-4652-4ee7-8a3a-6413df21e28d/f4142cba-f3eb-4917-b3bd-123d683f18d7
Body Parameter
{
"primary_location": false
}
Example Response
{
"id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"version": "e3ac9313-12b6-44e1-8094-aa113501e0a8",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"primary_location": false,
"billing_location": true,
"address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "2345 Test St",
"zip_code": "94109"
},
"created": 1628617987,
"modified": 1628617990
}
Edit a location based on the ID provided. The version parameter must match the latest location version.
Path Parameters
group_id |
The unique identifier of the group in Noyo |
location_id |
The unique identifier of the location in Noyo |
version |
The current version identifier of the location |
Request Body
display_name |
string | Display name for the group location |
address |
object |
|
primary_location |
boolean | Boolean field to determine whether the group location should be used as the primary group location |
billing_location |
boolean | Boolean field to determine whether the group location should be used as the billing group location |
Edit Location Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
display_name* |
string | Display name for the group location |
primary_location* |
boolean | Boolean field to determine whether the group location should be used as the primary group location |
billing_location* |
boolean | Boolean field to determine whether the group location should be used as the billing group location |
address* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Group Applications
Create a blank application
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/applications
Body Parameter
{
"carrier_id": "0b220d37-2057-465c-99af-b5cb10f4d172",
"application_type": "new",
"notes": "",
"carrier_group_id": "US00099"
}
Example Response
{
"application_type": "new",
"carrier_id": "0b220d37-2057-465c-99af-b5cb10f4d172",
"created": 1628617987,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"id": "ba1d1878-1d24-48f0-9ec0-ef7d2a603abf",
"modified": 1628617987,
"notes": "",
"status": "in_progress",
"status_notes": "",
"version": "44f71d9f-9c6b-49d0-b2b2-2662334e3e16"
}
After creating a group, you can then create one or more new applications (one per carrier). Just pass the carrier ID and carrier group ID (if known) for the carrier associated with the application and the application type. The carrier group ID will allow us to reference the group in the carrier’s system if that has already been allocated.
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Request Body
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
application_type* |
string | Type of application for the group with this carrier. One of: new, renewal, upsell |
notes |
string | General platform notes about the group application |
carrier_group_id |
string | An id given by the carrier to identify the group |
Create Group Application Response
application_type* |
string | Type of application for the group with this carrier. One of: new, renewal, upsell |
carrier_group_id* |
string | An id given by the carrier to identify the group |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
created* |
timestamp | The date the record was created |
group_id* |
uuid | Unique identifier of the associated group in Noyo |
id* |
uuid | Unique identifier of the record in Noyo |
modified* |
timestamp | The date the record was last updated |
notes* |
string | General platform notes about the group application |
status* |
string | Status of the application for the group. One of: action_required, canceled, in_progress, installed_at_carrier, noyo_review, ready_for_requests, unable_to_install, waiting_on_carrier |
status_notes* |
string | Additional notes about the application status with the carrier |
version* |
uuid | Current version of the record |
Get all group applications
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/applications
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"application_type": "new",
"carrier_group_id": "",
"carrier_id": "7368753c-5fdb-4cad-b70b-e97c48731f06",
"created": 1628693051,
"group_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"modified": 1628693051,
"notes": "",
"status": "in_progress",
"status_notes": "",
"version": "fb4e01c4-e054-4bd4-9948-f464a1931a00"
}
]
}
Returns a list of all applications for the given group
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Query Parameters
status |
The application status used to filter results |
carrier_id |
The associated carrier ID used to filter results |
carrier_group_id |
The associated carrier group ID used to filter results |
application_type |
The application type used to filter results |
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
sort_by |
The attribute on which to sort the group applications |
sort_direction |
Either asc or desc, to denote the data's direction |
Get all group applications response
meta* |
object |
|
response* |
array |
|
Get a single group application
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9
Example Response
{
"application_type": "new",
"carrier_group_id": "",
"carrier_id": "7368753c-5fdb-4cad-b70b-e97c48731f06",
"created": 1628693051,
"group_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"modified": 1628693051,
"notes": "",
"status": "in_progress",
"status_notes": "",
"version": "fb4e01c4-e054-4bd4-9948-f464a1931a00"
}
Returns the latest version of a single group application based on the ID provided.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Get a single group application response
application_type* |
string | Type of application for the group with this carrier. One of: new, renewal, upsell |
carrier_group_id* |
string | An id given by the carrier to identify the group |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
created* |
timestamp | The date the record was created |
group_id* |
uuid | Unique identifier of the associated group in Noyo |
id* |
uuid | Unique identifier of the record in Noyo |
modified* |
timestamp | The date the record was last updated |
notes* |
string | General platform notes about the group application |
status* |
string | Status of the application for the group. One of: action_required, canceled, in_progress, installed_at_carrier, noyo_review, ready_for_requests, unable_to_install, waiting_on_carrier |
status_notes* |
string | Additional notes about the application status with the carrier |
version* |
uuid | Current version of the record |
Edit a group application
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/aef5eb2a-1084-46dc-a6cc-aa56958495ff/7b8a7747-8e67-40fd-a9a3-a411cdd9a2d8
Body Parameter
{
"notes": "a sample note"
}
Example Response
{
"application_type": "new",
"carrier_id": "0b220d37-2057-465c-99af-b5cb10f4d172",
"created": 1628617987,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"id": "ba1d1878-1d24-48f0-9ec0-ef7d2a603abf",
"modified": 1628617987,
"notes": "",
"status": "waiting_on_carrier",
"status_notes": "",
"version": "44f71d9f-9c6b-49d0-b2b2-2662334e3e16"
}
Edit a group application based on the ID provided. The version parameter must match the latest group application version.
Path Parameters
application_id |
The unique identifier of the group application in Noyo |
version |
The current version identifier of the group application |
Request Body
carrier_group_id |
string | An id given by the carrier to identify the group |
notes |
string | General platform notes about the group application |
Edit Group Application Response
application_type* |
string | Type of application for the group with this carrier. One of: new, renewal, upsell |
carrier_group_id* |
string | An id given by the carrier to identify the group |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
created* |
timestamp | The date the record was created |
group_id* |
uuid | Unique identifier of the associated group in Noyo |
id* |
uuid | Unique identifier of the record in Noyo |
modified* |
timestamp | The date the record was last updated |
notes* |
string | General platform notes about the group application |
status* |
string | Status of the application for the group. One of: action_required, canceled, in_progress, installed_at_carrier, noyo_review, ready_for_requests, unable_to_install, waiting_on_carrier |
status_notes* |
string | Additional notes about the application status with the carrier |
version* |
uuid | Current version of the record |
Group Application Statuses
Group applications move through the following statuses as they progress with Noyo and the carrier.
| Status | Description |
|---|---|
| in_progress | All applications are “in_progress” while you add accompanying data. |
| waiting_on_carrier | The application has been submitted and the carrier is processing it. |
| action_required | Action from you is required to for successful processing. Notes and next steps are listed in the status_notes field on the group application object. |
| installed_at_carrier | The group application is successfully installed at the carrier and Noyo is processing the group's data to prepare for requests. |
| ready_for_requests | Member requests can be sent at any time. |
| unable_to_install | The carrier was unable to install this group application. Noyo provides accompanying notes in the status_notes field on the group application object. |
| noyo_review | Noyo is actively resolving an issue with the application; no action is needed from you. |
| canceled | You have canceled the group application, perhaps because it was filed in error, or new information has invalidated it. |
This diagram shows the potential paths for a group application.
Bank Accounts
Create a bank account
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/99b18a62-29f1-4586-85e8-de9dfb28987c/bank_accounts
Body Parameter
{
"account_number": "123456789",
"bank_name": "Bank of America",
"is_checking": true,
"routing_number": "123456789"
}
Example Response
{
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"version": "fb4e01c4-e054-4bd4-9948-f464a1931a00",
"created": 1628693051,
"modified": 1628693051,
"application_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"status": "created",
"bank_name": "******",
"account_number": "*****6789",
"routing_number": "*****6789",
"is_checking": true
}
Create a bank account. Only a single bank account is permitted for a particular group application. If a subsequent one is submitted, you will receive a 409 error.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Request Body
account_number* |
string | Account number |
bank_name* |
string | Name of the bank |
is_checking* |
boolean | Whether the account is a checking account |
routing_number* |
string | Routing number |
Create Bank Account Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
application_id* |
uuid | Unique identifier of the associated application in Noyo |
status* |
string | The bank account status. One of: created, wiped |
bank_name* |
string | Name of the bank |
account_number* |
string | Account number |
routing_number* |
string | Routing number |
is_checking* |
boolean | Whether the account is a checking account |
Bank account related data can be submitted to a carrier in conjunction with a group application, so insurance premiums can be billed for a given group.
Get all bank accounts for an application
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/99b18a62-29f1-4586-85e8-de9dfb28987c/bank_accounts
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "6b79effb-6d0d-4f98-a495-2981fe0aa4d2",
"version": "fb4e01c4-e054-4bd4-9948-f464a1931a00",
"created": 1628693051,
"modified": 1628693051,
"application_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"status": "created",
"bank_name": "******",
"account_number": "*****1234",
"routing_number": "*****1234",
"is_checking": true
},
{
"id": "f10ed996-17bf-4d27-9388-6469941948bb",
"version": "fb4e01c4-e054-4bd4-9948-e7e885fd1da9",
"created": 1628693051,
"modified": 1628693051,
"application_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"status": "created",
"bank_name": "******",
"account_number": "*****1234",
"routing_number": "*****1234",
"is_checking": true
}
]
}
Returns the latest version of all bank accounts related to the application whose ID was provided.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Get all bank accounts for an application response
meta* |
object |
|
response* |
array |
|
Get a single bank account
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/99b18a62-29f1-4586-85e8-de9dfb28987c/bank_accounts/10b78184-d9ac-4c8b-9f4b-67f8f8fe95f0
Example Response
{
"id": "10b78184-d9ac-4c8b-9f4b-67f8f8fe95f0",
"version": "fb4e01c4-e054-4bd4-9948-f464a1931a00",
"created": 1628693051,
"modified": 1628693051,
"application_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"status": "created",
"bank_name": "******",
"account_number": "*****6789",
"routing_number": "*****6789",
"is_checking": true
}
Returns the latest version of a single bank account based on the ID provided.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
bank_account_id |
The unique identifier of the bank account in Noyo |
Get a single bank account response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
application_id* |
uuid | Unique identifier of the associated application in Noyo |
status* |
string | The bank account status. One of: created, wiped |
bank_name* |
string | Name of the bank |
account_number* |
string | Account number |
routing_number* |
string | Routing number |
is_checking* |
boolean | Whether the account is a checking account |
Delete a bank account
Code Sample
curl -X DELETE
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/bank_accounts/aef5eb2a-1084-46dc-a6cc-aa56958495ff/7b8a7747-8e67-40fd-a9a3-a411cdd9a2d8
Delete a Bank Account based on the ID provided. The version parameter must match the latest Bank Account version.
Path Parameters
application_id |
The unique identifier of the group application in Noyo |
bank_account_id |
The unique identifier of the bank account in Noyo |
version |
The current version identifier of the bank account |
Delete Bank Account Response
A successful delete will yield a 204 No Content response.
Agents
Create an agent
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/agents
Body Parameter
{
"license_number": "123456789012",
"agent_details": {
"first_name": "John",
"last_name": "Doe",
"national_producer_number": "adipisicing velit dolor",
"tax_id_number": "55-9876543"
},
"agency_details": {
"name": "James Doe",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"general_agency_details": {
"name": "Doe James",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"commission_details": [
{}
],
"signature_date": "2021-01-01"
}
Example Response
{
"id": "969a2b7a-4ce5-42fa-812f-11b7191d9179",
"version": "267073b1-0be3-428d-98d9-aad87f292aef",
"license_number": "123456789012",
"agent_details": {
"first_name": "John",
"last_name": "Doe",
"national_producer_number": "adipisicing velit dolor",
"tax_id_number": "55-9876543"
},
"agency_details": {
"name": "James Doe",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"general_agency_details": {
"name": "Doe James",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"commission_details": [
{}
],
"signature_date": "2021-01-01",
"created": 1628617987,
"modified": 1628617987
}
Create a new agent for a group application
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Request Body
license_number |
string | License number of the agent |
agent_details |
object |
|
agency_details |
object |
|
general_agency_details |
object |
|
commission_details |
array |
|
signature_date |
date | The signature date for the agent on the application |
Create Agent Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
license_number* |
string | License number of the agent |
agent_details* |
object |
|
agency_details* |
object |
|
general_agency_details* |
object |
|
commission_details* |
array |
|
signature_date* |
date | The signature date for the agent on the application |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Get all agents for an application
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/agents
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "969a2b7a-4ce5-42fa-812f-11b7191d9179",
"version": "267073b1-0be3-428d-98d9-aad87f292aef",
"license_number": "123456789012",
"agent_details": {
"first_name": "John",
"last_name": "Doe",
"national_producer_number": "adipisicing velit dolor",
"tax_id_number": "55-9876543"
},
"agency_details": {
"name": "James Doe",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"general_agency_details": {
"name": "Doe James",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"commission_details": [
{}
],
"signature_date": "2021-01-01",
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all agents for the given application
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1. |
Get all agents for an application response
meta* |
object |
|
response* |
array |
|
Get a single agent
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/agents/83359c7e-a14c-4381-8826-c81f026ba947
Example Response
{
"id": "969a2b7a-4ce5-42fa-812f-11b7191d9179",
"version": "267073b1-0be3-428d-98d9-aad87f292aef",
"license_number": "123456789012",
"agent_details": {
"first_name": "John",
"last_name": "Doe",
"national_producer_number": "adipisicing velit dolor",
"tax_id_number": "55-9876543"
},
"agency_details": {
"name": "James Doe",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"general_agency_details": {
"name": "Doe James",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"commission_details": [
{}
],
"signature_date": "2021-01-01",
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single agent based on the ID provided
Path Parameters
agent_id |
The unique identifier of the agent in Noyo |
Get a single agent response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
license_number* |
string | License number of the agent |
agent_details* |
object |
|
agency_details* |
object |
|
general_agency_details* |
object |
|
commission_details* |
array |
|
signature_date* |
date | The signature date for the agent on the application |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit an agent
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/agents/83359c7e-a14c-4381-8826-c81f026ba947/4632c3f7-b120-4a37-9b10-5911098d40ee
Body Parameter
{
"license_number": "123456789013"
}
Example Response
{
"id": "969a2b7a-4ce5-42fa-812f-11b7191d9179",
"version": "267073b1-0be3-428d-98d9-aad87f292aef",
"license_number": "123456789013",
"agent_details": {
"first_name": "John",
"last_name": "Doe",
"national_producer_number": "adipisicing velit dolor",
"tax_id_number": "55-9876543"
},
"agency_details": {
"name": "James Doe",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"general_agency_details": {
"name": "Doe James",
"tax_id_number": "55-1234567",
"national_producer_number": "5556667"
},
"commission_details": [
{}
],
"signature_date": "2021-01-01",
"created": 1628617987,
"modified": 1628617987
}
Edit an agent based on the ID provided. The version parameter must match the latest agent version.
Path Parameters
agent_id |
The unique identifier of the agent in Noyo |
version |
The current version identifier of the agent |
Request Body
license_number |
string | License number of the agent |
agent_details |
object |
|
agency_details |
object |
|
general_agency_details |
object |
|
commission_details |
array |
|
signature_date |
date | The signature date for the agent on the application |
Edit Agent Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
license_number* |
string | License number of the agent |
agent_details* |
object |
|
agency_details* |
object |
|
general_agency_details* |
object |
|
commission_details* |
array |
|
signature_date* |
date | The signature date for the agent on the application |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Agent Contacts
Create an agent contact
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/agents/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts
Body Parameter
{
"first_name": "Michele",
"last_name": "Gorczany",
"title": "HR Professional",
"email": "michele.gorczany@gmail.com",
"phone_number": "+15555551212",
"types": [
"billing"
]
}
Example Response
{
"id": "ba1d1878-1d24-48f0-9ec0-ef7d2a603abf",
"version": "44f71d9f-9c6b-49d0-b2b2-2662334e3e16",
"created": 1628617987,
"modified": 1628617987,
"agent_id": "969a2b7a-4ce5-42fa-812f-11b7191d9179",
"first_name": "Michele",
"last_name": "Gorczany",
"title": "HR Professional",
"email": "michele.gorczany@gmail.com",
"phone_number": "+15555551212",
"types": [
"billing"
]
}
Creates a new agent contact for an agent
Path Parameters
agent_id |
The unique identifier of the agent in Noyo |
Request Body
first_name* |
string | First name of the agent contact |
last_name* |
string | Last name of the agent contact |
title* |
string | Job title of the agent contact |
email* |
string | Work email address of the agent contact |
phone_number |
string | Work phone number of the agent contact in E.164 format |
types* |
array | List of contact types for the agent contact. One of: billing, company, executive, online |
Create Agent Contact Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
agent_id* |
uuid | Unique identifier of the agent in Noyo |
first_name* |
string | First name of the agent contact |
last_name* |
string | Last name of the agent contact |
title* |
string | Job title of the agent contact |
email* |
string | Work email address of the agent contact |
phone_number |
string | Work phone number of the agent contact in E.164 format |
types* |
array | List of contact types for the agent contact. One of: billing, company, executive, online |
Get all agent contacts
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/agents/83359c7e-a14c-4381-8826-c81f026ba947/contacts
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "ba1d1878-1d24-48f0-9ec0-ef7d2a603abf",
"version": "44f71d9f-9c6b-49d0-b2b2-2662334e3e16",
"created": 1628617987,
"modified": 1628617987,
"agent_id": "969a2b7a-4ce5-42fa-812f-11b7191d9179",
"first_name": "Michele",
"last_name": "Gorczany",
"title": "HR Professional",
"email": "michele.gorczany@gmail.com",
"phone_number": "+15555551212",
"types": [
"billing"
]
}
]
}
Returns a list of all contacts for the given agent
Path Parameters
agent_id |
The unique identifier of the agent in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1. |
Get all agent contacts response
meta* |
object |
|
response* |
array |
|
Get a single agent contact
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/agents/83359c7e-a14c-4381-8826-c81f026ba947/contacts/a4e746df-ff1d-46ad-a8eb-f64b72acb828
Example Response
{
"id": "a4e746df-ff1d-46ad-a8eb-f64b72acb828",
"version": "44f71d9f-9c6b-49d0-b2b2-2662334e3e16",
"created": 1628617987,
"modified": 1628617987,
"agent_id": "83359c7e-a14c-4381-8826-c81f026ba947",
"first_name": "Michele",
"last_name": "Gorczany",
"title": "HR Professional",
"email": "michele.gorczany@gmail.com",
"phone_number": "+15555551212",
"types": [
"billing"
]
}
Returns the latest version of a single agent based on the ID provided
Path Parameters
agent_id |
The unique identifier of the agent in Noyo |
contact_id |
The unique identifier of the agent contact in Noyo |
Get a single agent contact response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
agent_id* |
uuid | Unique identifier of the agent in Noyo |
first_name* |
string | First name of the agent contact |
last_name* |
string | Last name of the agent contact |
title* |
string | Job title of the agent contact |
email* |
string | Work email address of the agent contact |
phone_number |
string | Work phone number of the agent contact in E.164 format |
types* |
array | List of contact types for the agent contact. One of: billing, company, executive, online |
Edit an agent contact
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/agents/83359c7e-a14c-4381-8826-c81f026ba947/contacts/a4e746df-ff1d-46ad-a8eb-f64b72acb828/015228ff-ea2e-48b0-a916-581dbf87958c
Body Parameter
{
"first_name": "Michele"
}
Example Response
{
"id": "a4e746df-ff1d-46ad-a8eb-f64b72acb828",
"version": "44f71d9f-9c6b-49d0-b2b2-2662334e3e16",
"created": 1628617987,
"modified": 1628617987,
"agent_id": "83359c7e-a14c-4381-8826-c81f026ba947",
"first_name": "Michele",
"last_name": "Gorczany",
"title": "HR Professional",
"email": "michele.gorczany@gmail.com",
"phone_number": "+15555551212",
"types": [
"billing"
]
}
Edit an agent contact based on the ID provided. The version parameter must match the latest agent contact version.
Path Parameters
agent_id |
The unique identifier of the agent in Noyo |
contact_id |
The unique identifier of the agent contact in Noyo |
version |
The current version identifier of the agent contact |
Request Body
first_name |
string | First name of the agent contact |
last_name |
string | Last name of the agent contact |
title |
string | Job title of the agent contact |
email |
string | Work email address of the agent contact |
phone_number |
string | Work phone number of the agent contact in E.164 format |
types |
array | List of contact types for the agent contact. One of: billing, company, executive, online |
Edit Agent Contact Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
agent_id* |
uuid | Unique identifier of the agent in Noyo |
first_name* |
string | First name of the agent contact |
last_name* |
string | Last name of the agent contact |
title* |
string | Job title of the agent contact |
email* |
string | Work email address of the agent contact |
phone_number |
string | Work phone number of the agent contact in E.164 format |
types* |
array | List of contact types for the agent contact. One of: billing, company, executive, online |
Group Coverages
Create group coverage
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/group_coverages
Body Parameter
{
"line_of_coverage": "medical",
"requested_effective_date": "2022-01-01",
"notes": "",
"existing_coverage": false
}
Example Response
{
"id": "1aed3daf-ffd4-4f7f-9a39-1de02a18937c",
"version": "fe5ac6c5-b245-40bc-b4b6-1b807ed2a619",
"application_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"line_of_coverage": "medical",
"requested_effective_date": "2022-01-01",
"notes": "",
"created": 1628617987,
"modified": 1628617987
}
Here you’ll be able to add the lines of coverage for your group, including type of coverage and the requested effective date.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Request Body
line_of_coverage* |
string | The line of coverage requested with the carrier application. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision |
requested_effective_date* |
date | Requested effective date for start of coverage |
notes |
string | General platform notes about the group coverage |
existing_coverage |
boolean | True if this line of coverage is currently active with the carrier |
Create Group Coverage Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
application_id* |
uuid | Unique identifier of the application in Noyo |
line_of_coverage* |
string | The line of coverage requested with the carrier application. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision |
requested_effective_date* |
date | Requested effective date for start of coverage |
notes |
string | General platform notes about the group coverage |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
existing_coverage |
boolean | True if this line of coverage is currently active with the carrier |
Get all group coverages for an application
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/group_coverages
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "1aed3daf-ffd4-4f7f-9a39-1de02a18937c",
"version": "fe5ac6c5-b245-40bc-b4b6-1b807ed2a619",
"application_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"line_of_coverage": "medical",
"requested_effective_date": "2022-01-01",
"notes": "",
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all group coverages for a given application
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get all group coverages response
meta* |
object |
|
response* |
array |
|
Get a single group coverage
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/group_coverages/a4e746df-ff1d-46ad-a8eb-f64b72acb828
Example Response
{
"id": "1aed3daf-ffd4-4f7f-9a39-1de02a18937c",
"version": "fe5ac6c5-b245-40bc-b4b6-1b807ed2a619",
"application_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"line_of_coverage": "medical",
"requested_effective_date": "2022-01-01",
"notes": "",
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single group coverage based on the ID provided.
Path Parameters
group_coverage_id |
The unique identifier of the group coverage in Noyo |
Get a single group coverage response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
application_id* |
uuid | Unique identifier of the application in Noyo |
line_of_coverage* |
string | The line of coverage requested with the carrier application. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision |
requested_effective_date* |
date | Requested effective date for start of coverage |
notes |
string | General platform notes about the group coverage |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
existing_coverage |
boolean | True if this line of coverage is currently active with the carrier |
Plans
Create a plan
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/group_coverages/a4e746df-ff1d-46ad-a8eb-f64b72acb828/coverage_plans
Body Parameter
{
"plan_name": "Premium Gold Plan",
"code": "D1",
"plan_type": "basic",
"product_type": "gold",
"network": "PPO",
"rate_details": [
{
"amount": 45.0,
"period": {
"amount": 1,
"unit": "month"
},
"coverage_level": "EE"
}
],
"benefit_details": [
"fsa"
],
"contribution_details": [
{
"contribution_rule_type": "percent",
"contribution_rule": {
"percentage": "100%"
},
"contribution_source": "employer_amount",
"contribution_target": "employee"
},
{
"contribution_rule_type": "percent",
"contribution_rule": {
"percentage": "25%"
},
"contribution_source": "employer_amount",
"contribution_target": "dependents"
}
],
"notes": "",
"existing_plan": false
}
Example Response
{
"id": "62c22d5d-7cb3-4fc0-9d17-ed0bdc461afe",
"version": "5ae6fbcf-8a87-4042-b602-d223ad420e69",
"group_coverage_id": "8d8b65e6-338e-4f49-86b0-b9a4ba18579d",
"plan_name": "Premium Gold Plan",
"code": "D1",
"plan_type": "basic",
"product_type": "gold",
"network": "PPO",
"rate_details": [
{
"amount": 45.0,
"period": {
"amount": 1,
"unit": "month"
},
"coverage_level": "EE"
}
],
"benefit_details": [
"fsa"
],
"contribution_details": [
{
"contribution_rule_type": "percent",
"contribution_rule": {
"percentage": "90%"
},
"contribution_source": "employer_amount",
"contribution_target": "employee"
}
],
"notes": "",
"existing_plan": false,
"created": 1628617987,
"modified": 1628617987
}
Here you can associate a plan with a line of coverage and then pass information about the plan like the name, network, waiting periods, and other details.
Path Parameters
group_coverage_id |
The unique identifier of the group coverage in Noyo |
Request Body
plan_name* |
string | Display name of the plan |
code |
string | The code for the plan. |
plan_type |
string | Plan type for basic or voluntary plans |
product_type |
string | Details about the product type |
network |
string | Details about the plan network |
rate_details |
array |
|
benefit_details |
array | The add-on benefits offered by the plan. |
contribution_details |
array |
|
cobra_rules |
object |
|
volume_rules |
string | Volume rules for the group critical illness plan |
waiting_period_rules |
array | The list of waiting period rules. |
termination_policy |
string | Termination policy for the coverage plan |
notes |
string | General platform notes about the coverage plan |
existing_plan |
boolean | True if this plan is currently active with the carrier |
coverage_details |
object |
|
Create Coverage Plan Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_coverage_id* |
uuid | Unique identifier of the group coverage in Noyo |
plan_name* |
string | Display name of the plan |
code |
string | The code for the plan. |
plan_type |
string | Plan type for basic or voluntary plans |
product_type |
string | Details about the product type |
network |
string | Details about the plan network |
rate_details |
array |
|
benefit_details |
array | The add-on benefits offered by the plan. |
contribution_details |
array |
|
cobra_rules |
object |
|
volume_rules |
string | Volume rules for the group critical illness plan |
waiting_period_rules |
array | The list of waiting period rules. |
termination_policy |
string | Termination policy for the coverage plan |
notes |
string | General platform notes about the coverage plan |
existing_plan |
boolean | True if this plan is currently active with the carrier |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
coverage_details |
object |
|
Get all plans for a group coverage
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/group_coverages/a4e746df-ff1d-46ad-a8eb-f64b72acb828/coverage_plans
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "62c22d5d-7cb3-4fc0-9d17-ed0bdc461afe",
"version": "5ae6fbcf-8a87-4042-b602-d223ad420e69",
"group_coverage_id": "8d8b65e6-338e-4f49-86b0-b9a4ba18579d",
"plan_name": "Premium Gold Plan",
"code": "D1",
"plan_type": "basic",
"product_type": "gold",
"network": "PPO",
"rate_details": [
{
"amount": 45.0,
"period": {
"amount": 1,
"unit": "month"
},
"coverage_level": "EE"
}
],
"benefit_details": [
"fsa"
],
"contribution_details": [
{
"contribution_rule_type": "percent",
"contribution_rule": {
"percentage": "90%"
},
"contribution_source": "employer_amount",
"contribution_target": "employee"
}
],
"notes": "",
"existing_plan": false,
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all coverage plans for a given group coverage
Path Parameters
group_coverage_id |
The unique identifier of the group coverage. |
Get all plans response
meta* |
object |
|
response* |
array |
|
Get a single plan
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/coverage_plans/07bfdaf1-426f-4d58-b2d4-d1b04ffb79eb
Example Response
{
"id": "62c22d5d-7cb3-4fc0-9d17-ed0bdc461afe",
"version": "5ae6fbcf-8a87-4042-b602-d223ad420e69",
"group_coverage_id": "8d8b65e6-338e-4f49-86b0-b9a4ba18579d",
"plan_name": "Premium Gold Plan",
"code": "D1",
"plan_type": "basic",
"product_type": "gold",
"network": "PPO",
"rate_details": [
{
"amount": 45.0,
"period": {
"amount": 1,
"unit": "month"
},
"coverage_level": "EE"
}
],
"benefit_details": [
"fsa"
],
"contribution_details": [
{
"contribution_rule_type": "percent",
"contribution_rule": {
"percentage": "90%"
},
"contribution_source": "employer_amount",
"contribution_target": "employee"
}
],
"notes": "",
"existing_plan": false,
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single coverage plan based on the ID provided.
Path Parameters
plan_id |
The unique identifier of the coverage plan in Noyo |
Get a single plan response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_coverage_id* |
uuid | Unique identifier of the group coverage in Noyo |
plan_name* |
string | Display name of the plan |
code |
string | The code for the plan. |
plan_type |
string | Plan type for basic or voluntary plans |
product_type |
string | Details about the product type |
network |
string | Details about the plan network |
rate_details |
array |
|
benefit_details |
array | The add-on benefits offered by the plan. |
contribution_details |
array |
|
cobra_rules |
object |
|
volume_rules |
string | Volume rules for the group critical illness plan |
waiting_period_rules |
array | The list of waiting period rules. |
termination_policy |
string | Termination policy for the coverage plan |
notes |
string | General platform notes about the coverage plan |
existing_plan |
boolean | True if this plan is currently active with the carrier |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
coverage_details |
object |
|
Edit a plan
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/coverage_plans/07bfdaf1-426f-4d58-b2d4-d1b04ffb79eb/98c158ce-e9df-4dd0-b7a6-48472c6583a6
Body Parameter
{
"plan_name": "Premium Silver Plan"
}
Example Response
{
"id": "62c22d5d-7cb3-4fc0-9d17-ed0bdc461afe",
"version": "5ae6fbcf-8a87-4042-b602-d223ad420e69",
"group_coverage_id": "8d8b65e6-338e-4f49-86b0-b9a4ba18579d",
"plan_name": "Premium Silver Plan",
"code": "D1",
"plan_type": "basic",
"product_type": "gold",
"network": "PPO",
"rate_details": [
{
"amount": 45.0,
"period": {
"amount": 1,
"unit": "month"
},
"coverage_level": "EE"
}
],
"benefit_details": [
"fsa"
],
"contribution_details": [
{
"contribution_rule_type": "percent",
"contribution_rule": {
"percentage": "90%"
},
"contribution_source": "employer_amount",
"contribution_target": "employee"
}
],
"notes": "",
"existing_plan": false,
"created": 1628617987,
"modified": 1628617987
}
Edit a coverage plan based on the ID provided. The version parameter must match the latest coverage plan version.
Path Parameters
plan_id |
The unique identifier of the coverage plan in Noyo |
version |
The current version identifier of the coverage plan |
Request Body
plan_name |
string | Display name of the plan |
code |
string | The code for the plan. |
plan_type |
string | Plan type for basic or voluntary plans |
product_type |
string | Details about the product type |
network |
string | Details about the plan network |
rate_details |
array |
|
benefit_details |
array | The add-on benefits offered by the plan. |
contribution_details |
array |
|
cobra_rules |
object |
|
volume_rules |
string | Volume rules for the group critical illness plan |
waiting_period_rules |
array | The list of waiting period rules. |
termination_policy |
string | Termination policy for the coverage plan |
notes |
string | General platform notes about the coverage plan |
existing_plan |
boolean | True if this plan is currently active with the carrier |
coverage_details |
object |
|
Edit Plan Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_coverage_id* |
uuid | Unique identifier of the group coverage in Noyo |
plan_name* |
string | Display name of the plan |
code |
string | The code for the plan. |
plan_type |
string | Plan type for basic or voluntary plans |
product_type |
string | Details about the product type |
network |
string | Details about the plan network |
rate_details |
array |
|
benefit_details |
array | The add-on benefits offered by the plan. |
contribution_details |
array |
|
cobra_rules |
object |
|
volume_rules |
string | Volume rules for the group critical illness plan |
waiting_period_rules |
array | The list of waiting period rules. |
termination_policy |
string | Termination policy for the coverage plan |
notes |
string | General platform notes about the coverage plan |
existing_plan |
boolean | True if this plan is currently active with the carrier |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
coverage_details |
object |
|
Employees
Create an employee
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/employees
Body Parameter
{
"employment": {
"employment_dates": {
"full_time_start": "2021-01-01",
"hire_date": "2021-01-01"
},
"employment_status": "full-time",
"occupation": "CTO",
"salary": {
"amount": 50000.0,
"type": "salary",
"unit": "annual"
}
},
"person": {
"contact": {
"email_address": "francis@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1984-01-02",
"first_name": "Francis",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "married",
"sex": "M",
"ssn": "987654320"
}
}
Example Response
{
"id": "59a344a3-25ac-4b00-95ad-37ca518696e0",
"version": "78f71504-2f53-4459-be71-6b7f6c30149e",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"employment": {
"employment_dates": {
"full_time_start": "2021-01-01",
"hire_date": "2021-01-01"
},
"employment_status": "full-time",
"occupation": "CTO",
"salary": {
"amount": 50000.0,
"type": "salary",
"unit": "annual"
}
},
"person": {
"contact": {
"email_address": "francis@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1984-01-02",
"first_name": "Francis",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "married",
"sex": "M",
"ssn": "987654320"
},
"created": 1628617987,
"modified": 1628617987
}
When you add employees to your group, you’ll pass information like their hire date, employment status, and basic demographic information (address, DOB, SSN, etc.).
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Request Body
employment |
object |
|
person* |
object |
|
Create Employee Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
employment* |
object |
|
person* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Get all employees
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/employees
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "59a344a3-25ac-4b00-95ad-37ca518696e0",
"version": "dd313db2-7aa1-4390-aa96-e3678091b57c",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"employment": {
"employment_dates": {
"full_time_start": "2021-01-01",
"hire_date": "2021-01-01"
},
"employment_status": "full-time",
"occupation": "CTO",
"salary": {
"amount": 50000.0,
"type": "salary",
"unit": "annual"
}
},
"person": {
"contact": {
"email_address": "francis@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1984-01-02",
"first_name": "Jaime",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "married",
"sex": "M",
"ssn": "987654320"
},
"created": 1628617987,
"modified": 1628617990
}
]
}
Returns a list of all employees for a given group
Path Parameters
group_id |
The unique identifier of the group in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get employees response
meta* |
object |
|
response* |
array |
|
Get a single employee
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/employees/2613a221-d3c8-4c8a-86d5-e7e885fd1da9
Example Response
{
"id": "59a344a3-25ac-4b00-95ad-37ca518696e0",
"version": "dd313db2-7aa1-4390-aa96-e3678091b57c",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"employment": {
"employment_dates": {
"full_time_start": "2021-01-01",
"hire_date": "2021-01-01"
},
"employment_status": "full-time",
"occupation": "CTO",
"salary": {
"amount": 50000.0,
"type": "salary",
"unit": "annual"
}
},
"person": {
"contact": {
"email_address": "francis@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1984-01-02",
"first_name": "Jaime",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "married",
"sex": "M",
"ssn": "987654320"
},
"created": 1628617987,
"modified": 1628617990
}
Returns the latest version of a single employee based on the ID provided.
Path Parameters
employee_id |
The unique identifier of the employee in Noyo |
Get a single employee response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
employment* |
object |
|
person* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit an employee
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/employees/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/24b1f863-d249-48d1-a2b4-c61f0a437938
Body Parameter
{
"person": {
"first_name": "Jaime"
}
}
Example Response
{
"id": "59a344a3-25ac-4b00-95ad-37ca518696e0",
"version": "dd313db2-7aa1-4390-aa96-e3678091b57c",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"employment": {
"employment_dates": {
"full_time_start": "2021-01-01",
"hire_date": "2021-01-01"
},
"employment_status": "full-time",
"occupation": "CTO",
"salary": {
"amount": 50000.0,
"type": "salary",
"unit": "annual"
}
},
"person": {
"contact": {
"email_address": "francis@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1984-01-02",
"first_name": "Jaime",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "married",
"sex": "M",
"ssn": "987654320"
},
"created": 1628617987,
"modified": 1628617990
}
Edit an employee based on the ID provided. The version parameter must match the latest employee version.
Path Parameters
employee_id |
The unique identifier of the employee in Noyo |
version |
The current version identifier of the employee |
Request Body
employment |
object |
|
person |
object |
|
Edit Employee Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_id* |
uuid | Unique identifier of the group in Noyo |
employment* |
object |
|
person* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Dependents
Create a dependent
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/employees/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/dependents
Body Parameter
{
"relationship": "child",
"person": {
"contact": {
"email_address": "jamie@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "2000-01-02",
"first_name": "Jamie",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "single",
"sex": "F",
"ssn": "384032999"
}
}
Example Response
{
"id": "5e8d64cd-9152-4791-884d-bd2bd4899f17",
"version": "dd321baa-a48f-4e09-9709-827c3f0eb660",
"employee_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"relationship": "child",
"person": {
"contact": {
"email_address": "jamie@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "2000-01-02",
"first_name": "Jamie",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "single",
"sex": "F",
"ssn": "384032999"
},
"created": 1628617987,
"modified": 1628617987
}
Now, you can associate dependents who are electing coverage with respective employees.
Path Parameters
employee_id |
The unique identifier of the employee in Noyo |
Request Body
relationship* |
string | Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child |
person* |
object |
|
Create Dependent Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
employee_id* |
uuid | Unique identifier of the employee in Noyo |
relationship* |
string | Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child |
person* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Get all dependents for an employee
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/employees/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/dependents
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"version": "669fbe16-9960-4069-91aa-832ada3f4e42",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"relationship": "spouse",
"person": {
"contact": {
"email_address": "diane@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1982-01-02",
"first_name": "Diane",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "",
"sex": "F",
"ssn": "987654321"
},
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all dependents for a given employee
Path Parameters
employee_id |
The unique identifier of the employee in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get all dependents response
meta* |
object |
|
response* |
array |
|
Get a single dependent
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/dependents/5e8d64cd-9152-4791-884d-bd2bd4899f17
Example Response
{
"id": "5e8d64cd-9152-4791-884d-bd2bd4899f17",
"version": "669fbe16-9960-4069-91aa-832ada3f4e42",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"relationship": "spouse",
"person": {
"contact": {
"email_address": "diane@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1982-01-02",
"first_name": "Diane",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "married",
"sex": "F",
"ssn": "987654321"
},
"created": 1628617987,
"modified": 1628617987
}
Returns the latest version of a single dependent based on the ID provided.
Path Parameters
dependent_id |
The unique identifier of the dependent in Noyo |
Get a single dependent response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
employee_id* |
uuid | Unique identifier of the employee in Noyo |
relationship* |
string | Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child |
person* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit a dependent
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/dependents/5e8d64cd-9152-4791-884d-bd2bd4899f17/dd321baa-a48f-4e09-9709-827c3f0eb660
Body Parameter
{
"relationship": "child"
}
Example Response
{
"id": "5e8d64cd-9152-4791-884d-bd2bd4899f17",
"version": "669fbe16-9960-4069-91aa-832ada3f4e42",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"relationship": "child",
"person": {
"contact": {
"email_address": "diane@testemail.com",
"email_address_type": "home",
"home_phone": "+12065551234"
},
"date_of_birth": "1982-01-02",
"first_name": "Diane",
"home_address": {
"city": "San Francisco",
"county": "San Francisco",
"state": "CA",
"street_one": "1234 Home Ave",
"zip_code": "94107"
},
"last_name": "Johnson",
"marital_status": "",
"sex": "F",
"ssn": "987654321"
}
}
Edit a dependent based on the ID provided. The version parameter must match the latest dependent version.
Path Parameters
dependent_id |
The unique identifier of the employee in Noyo |
version |
The current version identifier of the dependent |
Request Body
relationship |
string | Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child |
person |
object |
|
Edit Dependent Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
employee_id* |
uuid | Unique identifier of the employee in Noyo |
relationship* |
string | Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child |
person* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Member Elections
Create a member election
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/coverage_plans/a7356150-6c76-462d-a771-a88b50daabff/member_elections
Body Parameter
{
"member_id": "ba9c73a6-d0a6-47f6-b32c-50fd37961651",
"member_type": "employee",
"status": "enrolling"
}
Example Response
{
"id": "51c43bdf-45dd-4361-8b97-047dfa22cf02",
"version": "383c864b-ab89-44bf-93b7-abab4ced0bd9",
"member_id": "ba9c73a6-d0a6-47f6-b32c-50fd37961651",
"member_type": "employee",
"plan_id": "47a4b463-fb15-4d10-b3c3-69a619f166ba",
"status": "enrolling",
"created": 1628617987,
"modified": 1628617987
}
Create a new member election for an coverage plan
Path Parameters
plan_id |
The unique identifier of the coverage plan in Noyo |
Request Body
member_id* |
uuid | Unique identifier of the member in Noyo |
member_type* |
string | Type of member electing or waiving coverage. One of: dependent, employee |
status* |
string | Status of the member election on the coverage plan. One of: enrolling, waiving |
volume |
string | Volume amount requested for the enrolling member |
Create Member Election Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
member_id* |
uuid | Unique identifier of the member in Noyo |
member_type* |
string | Type of member electing or waiving coverage. One of: dependent, employee |
plan_id* |
uuid | Unique identifier of the coverage plan in Noyo |
volume |
string | Volume amount requested for the enrolling member |
status* |
string | Status of the member election on the coverage plan. One of: enrolling, waiving |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Get all member elections for a coverage plan
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/coverage_plans/a7356150-6c76-462d-a771-a88b50daabff/member_elections
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "51c43bdf-45dd-4361-8b97-047dfa22cf02",
"version": "383c864b-ab89-44bf-93b7-abab4ced0bd9",
"member_id": "ba9c73a6-d0a6-47f6-b32c-50fd37961651",
"member_type": "employee",
"plan_id": "47a4b463-fb15-4d10-b3c3-69a619f166ba",
"status": "enrolling",
"created": 1628617987,
"modified": 1628617987
}
]
}
Returns a list of all member elections for a given coverage plan
Path Parameters
plan_id |
The unique identifier of the coverage plan in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get member elections response
meta* |
object |
|
response* |
array |
|
Get a single member election
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/member_elections/2613a221-d3c8-4c8a-86d5-e7e885fd1da9
Example Response
{
"id": "51c43bdf-45dd-4361-8b97-047dfa22cf02",
"version": "383c864b-ab89-44bf-93b7-abab4ced0bd9",
"member_id": "ba9c73a6-d0a6-47f6-b32c-50fd37961651",
"member_type": "employee",
"plan_id": "47a4b463-fb15-4d10-b3c3-69a619f166ba",
"status": "enrolling",
"created": 1628617987,
"modified": 1628617987
}
Returns a member election.
Path Parameters
member_election_id |
The unique identifier of the member election |
Get a single member election response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
member_id* |
uuid | Unique identifier of the member in Noyo |
member_type* |
string | Type of member electing or waiving coverage. One of: dependent, employee |
plan_id* |
uuid | Unique identifier of the coverage plan in Noyo |
volume |
string | Volume amount requested for the enrolling member |
status* |
string | Status of the member election on the coverage plan. One of: enrolling, waiving |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Edit a member election
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/member_elections/94e57625-1c0d-47fe-9a63-fe7320ecef12/dcf941c6-094d-450a-9ed6-b15bbdb2188d
Body Parameter
{
"status": "waiving"
}
Example Response
{
"id": "51c43bdf-45dd-4361-8b97-047dfa22cf02",
"version": "383c864b-ab89-44bf-93b7-abab4ced0bd9",
"member_id": "ba9c73a6-d0a6-47f6-b32c-50fd37961651",
"member_type": "employee",
"plan_id": "47a4b463-fb15-4d10-b3c3-69a619f166ba",
"status": "waiving",
"created": 1628617987,
"modified": 1628617987
}
Edit a member election based on the ID provided. The version parameter must match the latest member election version.
Path Parameters
member_election_id |
The unique identifier of the member election in Noyo |
version |
The current version identifier of the member election |
Request Body
plan_id |
uuid | Unique identifier of the coverage plan in Noyo |
volume |
string | Volume amount requested for the enrolling member |
status |
string | Status of the member election on the coverage plan. One of: enrolling, waiving |
Edit Member Election Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
member_id* |
uuid | Unique identifier of the member in Noyo |
member_type* |
string | Type of member electing or waiving coverage. One of: dependent, employee |
plan_id* |
uuid | Unique identifier of the coverage plan in Noyo |
volume |
string | Volume amount requested for the enrolling member |
status* |
string | Status of the member election on the coverage plan. One of: enrolling, waiving |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Document Upload
Create an application document
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/documents
Body Parameter
{
"document_type": "broker_signature",
"name": "Broker Signature Image"
}
Example Response
{
"id": "13794bc7-0bd9-45a4-9655-ba9ce2f2eff5",
"version": "9d085fb5-1cdb-4987-b683-73bda1097682",
"created": 1628617987,
"modified": 1628617987,
"application_id": "93431a48-6174-49f2-9c29-a60c9fb99b80",
"name": "My File",
"notes": "",
"status": "in_progress",
"status_notes": "",
"required": true,
"file_upload_id": "a2f27a71-48ca-476e-9096-68422c2afcbf",
"template_file_key": "https://example.noyo.com/templates/test-group/UniversalApplication.pdf",
"document_type": "broker_signature"
}
Create a new document submission attached to an application. This endpoint provisions a new document upload and creates a new application document to be attached to the application. Use this endpoint to submit any files not already requested by the application.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Request Body
document_type* |
string | Type of the document |
name* |
string | Display name of the application document |
notes |
string | General platform notes about the application document |
Create Application Document Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
application_id* |
uuid | Unique identifier of the application in Noyo |
name* |
string | Display name of the application document |
notes* |
string | General platform notes about the application document |
status* |
string | Status of the application document. One of: accepted, in_progress, incomplete, noyo_review, rejected, submitted, wiped |
status_notes* |
string | Additional notes about the application document status with the carrier |
required* |
boolean | True if this document is required to submit the application |
file_upload_id |
uuid | Unique identifier of the file upload id |
template_file_key* |
string | GCS link to the template file stored in Noyo, if available |
document_type* |
string | Type of the document |
Get all application documents for an application
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/documents
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "13794bc7-0bd9-45a4-9655-ba9ce2f2eff5",
"version": "9d085fb5-1cdb-4987-b683-73bda1097682",
"created": 1628617987,
"modified": 1628617987,
"application_id": "93431a48-6174-49f2-9c29-a60c9fb99b80",
"name": "My File",
"notes": "",
"status": "in_progress",
"status_notes": "",
"required": true,
"file_upload_id": "a2f27a71-48ca-476e-9096-68422c2afcbf",
"template_file_key": "https://example.noyo.com/templates/test-group/UniversalApplication.pdf",
"document_type": "broker_signature"
}
]
}
Get a list of all documents associated with a carrier application.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get application documents response
meta* |
object |
|
response* |
array |
|
Get a single application document
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9
Example Response
{
"application_type": "new",
"carrier_group_id": "",
"carrier_id": "7368753c-5fdb-4cad-b70b-e97c48731f06",
"created": 1628693051,
"group_id": "99b18a62-29f1-4586-85e8-de9dfb28987c",
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"modified": 1628693051,
"notes": "",
"status": "in_progress",
"status_notes": "",
"version": "fb4e01c4-e054-4bd4-9948-f464a1931a00"
}
Returns the latest version of a single group application based on the ID provided.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
Get a single application document response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
application_id* |
uuid | Unique identifier of the application in Noyo |
name* |
string | Display name of the application document |
notes* |
string | General platform notes about the application document |
status* |
string | Status of the application document. One of: accepted, in_progress, incomplete, noyo_review, rejected, submitted, wiped |
status_notes* |
string | Additional notes about the application document status with the carrier |
required* |
boolean | True if this document is required to submit the application |
file_upload_id |
uuid | Unique identifier of the file upload id |
template_file_key* |
string | GCS link to the template file stored in Noyo, if available |
document_type* |
string | Type of the document |
Upload an application document
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://document-upload.noyo.com/api/v1/files/e0b5e77b-d1bb-4a0f-a323-79c1ab9f3f06
Body (sent as MIME type
multipart/form-data)
`file` should be the file contents
Example Response
204 No Content
Once you have created an application document, you may upload the associated file to our document upload service.
Send in the file to the document upload service as file in form data. Asychronously, we will associate this file with your application document record, using the common file_upload_id.
Path Parameters
file_upload_id |
The unique identifier you received when creating the application document in the group install service |
Edit an application document
Code Sample
curl -X PATCH
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/documents/b257bf08-75d9-495c-9b9f-ea12a574d176/408bb91b-83db-4cc0-a562-109603a55488
Body Parameter
{
"notes": "This census is from August 2021"
}
Example Response
{
"id": "13794bc7-0bd9-45a4-9655-ba9ce2f2eff5",
"version": "9d085fb5-1cdb-4987-b683-73bda1097682",
"created": 1628617987,
"modified": 1628617987,
"application_id": "93431a48-6174-49f2-9c29-a60c9fb99b80",
"name": "My File",
"notes": "This census is from August 2021",
"status": "in_progress",
"status_notes": "",
"required": true,
"file_upload_id": "a2f27a71-48ca-476e-9096-68422c2afcbf",
"template_file_key": "https://example.noyo.com/templates/test-group/UniversalApplication.pdf",
"document_type": "broker_signature"
}
Edit an application document based on the ID provided. The version parameter must match the latest application document version. When the group_file_id is not present, this method will update properties and metadata about an existing application document.
Path Parameters
application_id |
The unique identifier of the application in Noyo |
document_id |
The unique identifier of the application document in Noyo |
version |
The current version identifier of the application document |
Request Body
name |
string | Display name of the application document |
notes |
string | General platform notes about the application document |
Edit Application Document Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
application_id* |
uuid | Unique identifier of the application in Noyo |
name* |
string | Display name of the application document |
notes* |
string | General platform notes about the application document |
status* |
string | Status of the application document. One of: accepted, in_progress, incomplete, noyo_review, rejected, submitted, wiped |
status_notes* |
string | Additional notes about the application document status with the carrier |
required* |
boolean | True if this document is required to submit the application |
file_upload_id |
uuid | Unique identifier of the file upload id |
template_file_key* |
string | GCS link to the template file stored in Noyo, if available |
document_type* |
string | Type of the document |
Application submission
Once all the required documents have been uploaded to Noyo and associated with the application, you can then use this endpoint to kick off the full submission to the carrier. There is no request body needed on this request. At this point, we will run some validations on the entirety of the application. If anything is amiss, we will return 422 from this request.
Code Sample
curl -X PUT
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://group-installation.noyo.com/api/v1/applications/aef5eb2a-1084-46dc-a6cc-aa56958495ff/7b8a7747-8e67-40fd-a9a3-a411cdd9a2d8/submit
Example Response
{
"application_type": "new",
"carrier_id": "0b220d37-2057-465c-99af-b5cb10f4d172",
"created": 1628617987,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"id": "aef5eb2a-1084-46dc-a6cc-aa56958495ff",
"modified": 1628617987,
"notes": "",
"status": "waiting_on_carrier",
"status_notes": "",
"version": "7b8a7747-8e67-40fd-a9a3-a411cdd9a2d8"
}
Submits a group application to the carrier based on the ID provided.
Path Parameters
application_id |
The unique identifier of the group application in Noyo |
version |
The current version identifier of the group application |
Submit Group Application Response
application_type* |
string | Type of application for the group with this carrier. One of: new, renewal, upsell |
carrier_group_id* |
string | An id given by the carrier to identify the group |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
created* |
timestamp | The date the record was created |
group_id* |
uuid | Unique identifier of the associated group in Noyo |
id* |
uuid | Unique identifier of the record in Noyo |
modified* |
timestamp | The date the record was last updated |
notes* |
string | General platform notes about the group application |
status* |
string | Status of the application for the group. One of: action_required, canceled, in_progress, installed_at_carrier, noyo_review, ready_for_requests, unable_to_install, waiting_on_carrier |
status_notes* |
string | Additional notes about the application status with the carrier |
version* |
uuid | Current version of the record |
Group Connections
Group connections enable you to set up a carrier connection through Noyo for a group that you administer. To create a group connection, the group must already be installed in the carrier’s system, and Noyo must have permission to manage enrollments for the group.
Note: If you installed the group with the carrier through Noyo, you do not need to set up a connection as well.
Create Group Connection
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/group_connections
Body Parameter
{
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"federal_ein": "123456789",
"group_data": {
"carrier_group_id": "10000000",
"group_name": "Test Company"
}
}
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
"created": 1557329939,
"modified": 1557329939,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
"request_type": "initial",
"status": "created",
"group_data": {
"carrier_group_id": "10000000",
"group_name": "Test Company"
}
}
Create a new connection for a brand new group with a given carrier
Request Body
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
federal_ein |
string | Federal Employer Identification Number for the new group/company |
group_data* |
object |
|
Create Group Connection Response
id* |
uuid | Unique identifier of the group connection in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
completed |
timestamp | Timestamp indicating when a group connection was marked as completed. |
organization_id* |
uuid | Unique identifier of the platform or broker organization in Noyo |
group_id |
uuid | ID of associated group model |
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
request_type* |
string | Type of the group connection |
status* |
string | Status of the group connection. One of: action_required, carrier_authorization, completed, created, noyo_review, processing, unable_to_connect, waiting_on_carrier |
group_data* |
object |
|
setup_result* |
object | More information about the result of the group connection |
Error Cases
| 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. |
Adding Another Carrier
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/group_connections
Body Parameter
{
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"group_data": {
"carrier_group_id": "10000000"
}
}
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
"created": 1557329939,
"modified": 1557329939,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
"request_type": "incremental",
"status": "created",
"group_data": {
"carrier_group_id": "10000000"
}
}
Create a new carrier connection for an existing group
Path Parameters
group_id |
The unique identifier of the group for which you would like to add a carrier connection |
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
group_data* |
object |
|
Get Single Group Connection
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/group_connections/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
"created": 1557329939,
"modified": 1557392400,
"completed": 1557392400,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"group_id": "9e629e41-c706-4efd-9fbb-1ff2573fc67e",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"request_type": "initial",
"status": "completed",
"group_data": {
"carrier_group_id": "10000000",
"group_name": "Test Company"
},
"setup_result": {}
}
Returns the latest status of a single group connection based on the ID provided.
Path Parameters
connection_id |
The unique identifier of the group connection you would like to view |
Get Single Group Connection Response
Setup Result
The setup_result's structure will depend on the group connection's status.
If in noyo_review, action_required, waiting_on_carrier, or unable_to_connect statuses, it may contain an error string that gives further details about the specific issue involved.
For other statuses, the setup_result will be empty.
id* |
uuid | Unique identifier of the group connection in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
completed |
timestamp | Timestamp indicating when a group connection was marked as completed. |
organization_id* |
uuid | Unique identifier of the platform or broker organization in Noyo |
group_id |
uuid | ID of associated group model |
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
request_type* |
string | Type of the group connection |
status* |
string | Status of the group connection. One of: action_required, carrier_authorization, completed, created, noyo_review, processing, unable_to_connect, waiting_on_carrier |
group_data* |
object |
|
setup_result* |
object | More information about the result of the group connection |
Get Group Connections
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/group_connections
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
"created": 1557329939,
"modified": 1557392400,
"completed": 1557392400,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"request_type": "initial",
"status": "processing",
"group_data": {
"carrier_group_id": "10000000",
"group_name": "Test Company"
}
}
]
}
Returns a list of all group connections.
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
status |
Status of the group connection for which you would like to filter. Multiple statuses can be used, separated by a comma. |
carrier_id |
The unique identifier of the carrier for which you would like to view group connection requests |
organization_id |
The unique identifier of the organization for which you would like to view group connection requests |
sort_by |
The attribute on which to sort the group connections |
sort_direction |
Either asc or desc, to denote the data's direction |
Get All Group Connections Response
meta* |
object |
|
response* |
array |
|
Group Connections in a Group
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2ce3b54a-2535-4803-b218-e6b44081d418/group_connections
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
"created": 1557329939,
"modified": 1557392400,
"completed": 1557392400,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"request_type": "initial",
"status": "processing",
"group_data": {
"carrier_group_id": "10000000",
"group_name": "Test Company"
}
}
]
}
Returns a list of all group connections for a given group ID.
Path Parameters
group_id |
The unique identifier of the associated group in Noyo |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
sort_by |
The attribute on which to sort the group connections |
sort_direction |
Either asc or desc, to denote the data's direction |
status |
Status of group connection for which you would like to filter. Multiple statuses can be used, separated by a comma. |
Group Structure Mapping
Benefits platforms can use Noyo’s tool to map account and plan information between their systems and the carrier’s. You will need to submit an account structure for each group that will be mapped; this information populates the conditions in the Group Structure Mapping tool.
Create Account Structure
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/3e366930-df4d-11eb-ba80-0242ac130004/platform_account_structures
Body Parameter
{
"account_structure": {
"account_structure_fields": [
{
"field_name": "BranchName",
"field_type": "string",
"existing_value_set": [
"North Branch",
"HQ",
"Springfield"
]
}
],
"plans": {
"group_medical_plans": [
"Medical Plan A",
"Medical Plan B"
],
"group_dental_plans": [
"Dental Plan Low",
"Dental Plan High"
]
}
},
"start_date": "2021-01-12"
}
Example Response
{
"id": "3e366930-df4d-11eb-ba80-0242ac130004",
"version": "5200a894-81c5-4c41-8519-86c32e9a9965",
"created": 1626281253,
"modified": 1626281253,
"group_id": "3e366930-df4d-11eb-ba80-0242ac130004",
"account_structure": {
"account_structure_fields": [
{
"field_name": "BranchName",
"field_type": "string",
"existing_value_set": [
"North Branch",
"HQ",
"Springfield"
]
}
],
"plans": {
"group_medical_plans": [
"Medical Plan A",
"Medical Plan B"
],
"group_dental_plans": [
"Dental Plan Low",
"Dental Plan High"
]
}
}
}
Create a new Platform Account Structure
Path Parameters
group_id |
Unique identifier of the associated group in the Noyo system |
Request Body
account_structure* |
object |
|
start_date |
date | Effective start date of the record, defaults to today |
end_date |
date | Effective end date of the record |
Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
account_structure* |
object |
|
Get Account Structure by Group
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2705bb9f-3c90-4400-a4e7-0bc9d48e677c/platform_account_structures
Example Response
{
"id": "2705bb9f-3c90-4400-a4e7-0bc9d48e677c",
"version": "7a2b0437-4027-4251-9e71-85384c0eb1c9",
"group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
"account_structure": {
"account_structure_fields": [
{
"field_name": "BranchName",
"field_type": "string",
"existing_value_set": [
"North Branch",
"HQ",
"Springfield"
]
}
],
"plans": {
"group_medical_plans": [
"Medical Plan A",
"Medical Plan B"
],
"group_dental_plans": [
"Dental Plan Low",
"Dental Plan High"
]
}
}
}
Retrieve a Platform Account Structure by Group
Path Parameters
group_id |
The unique identifier of the group you want to get a platform account structure for |
Query Parameters
effective_date |
The relative date on which to view the state of the record |
Get Account Structure by Group Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
account_structure* |
object |
|
Get Account Structure By ID
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/platform_account_structures/2705bb9f-3c90-4400-a4e7-0bc9d48e677c
Example Response
{
"id": "2705bb9f-3c90-4400-a4e7-0bc9d48e677c",
"version": "7a2b0437-4027-4251-9e71-85384c0eb1c9",
"group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
"account_structure": {
"account_structure_fields": [
{
"field_name": "BranchName",
"field_type": "string",
"existing_value_set": [
"North Branch",
"HQ",
"Springfield"
]
}
],
"plans": {
"group_medical_plans": [
"Medical Plan A",
"Medical Plan B"
],
"group_dental_plans": [
"Dental Plan Low",
"Dental Plan High"
]
}
}
}
Retrieve a Platform Account Structure
Path Parameters
platform_account_structure_id |
The unique identifier of the platform account structure to be retrieved. |
Query Parameters
effective_date |
The relative date on which to view the state of the record |
Get Account Structure Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
account_structure* |
object |
|
Edit Account Structure
Code Sample
curl -X PUT
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/platform_account_structures/3e366930-df4d-11eb-ba80-0242ac130004/5200a894-81c5-4c41-8519-86c32e9a9965
Body Parameter
{
"account_structure": {
"account_structure_fields": [
{
"field_name": "BranchName",
"field_type": "date",
"existing_value_set": [
"North Branch",
"HQ",
"Springfield"
]
}
],
"plans": {
"group_medical_plans": [
"Medical Plan A",
"Medical Plan B"
],
"group_dental_plans": [
"Dental Plan Low",
"Dental Plan High"
]
}
}
}
Example Response
{
"id": "3e366930-df4d-11eb-ba80-0242ac130004",
"version": "5200a894-81c5-4c41-8519-86c32e9a9965",
"created": 1557512389,
"modified": 1543215342,
"group_id": "3e366930-df4d-11eb-ba80-0242ac130004",
"account_structure": {
"account_structure_fields": [
{
"field_name": "BranchName",
"field_type": "date",
"existing_value_set": [
"North Branch",
"HQ",
"Springfield"
]
}
],
"plans": {
"group_medical_plans": [
"Medical Plan A",
"Medical Plan B"
],
"group_dental_plans": [
"Dental Plan Low",
"Dental Plan High"
]
}
}
}
Edit a platform account structure based on the ID provided. The version parameter must match the latest platform account structure version.
Path Parameters
platform_account_structure_id |
Unique identifier of the platform account structure in the Noyo system |
version |
Current version of the model |
Query Parameters
effective_date |
The relative date on which to view the state of the record |
Request Body
account_structure* |
object |
|
effective_date |
date | Effective date for target record to update, defaults to today |
Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
account_structure* |
object |
|
Policy Management
Creating Member Requests
Member requests and member transactions are the heart and soul of the Noyo group benefits API. They represent the core operations you want to carry out on behalf of members (employees and dependents) at one or many carriers. The following types of member requests are supported by the Noyo platform:
- Open Enrollment
- New Hire Enrollment
- Qualifying Life Event
- Termination
- Demographic Change
- COBRA Enrollment
- COBRA Open Enrollment
- COBRA Qualifying Life Event
- COBRA Termination
Each member request is attached to an employee, changes you wish to make to dependents are done via a member request attached to the employee. Each member request will contain many member transactions, which represent smaller sub-operations being carried out at a carrier partner. For example, a New Hire Enrollment member request may result in two member transactions: one to add medical coverage at Carrier A, and a second to add dental and vision coverage at Carrier B. More details about member requests and associated transactions follows.
Member Request Statuses
The following are possible member request statuses that you might receive when fetching member request(s) from the API.
| Key | Description |
|---|---|
processing |
We are communicating the member request changes to the carrier(s) involved. |
completed |
A request is completed after all transactions with all carriers have been processed. This may take seconds or longer, depending on the carrier and request type. The results of the member request have been reflected in the carrier system at this point. |
failed |
Requests will only move to the failed status if for an unexpected reason we were unable to fulfill at the carrier. You should expect very few member requests to transition into this status. |
canceled |
Requests will be moved to the canceled status if a subsequent member request supersedes it. |
As far as state transitions, expect the progression to be linear, from processing to either completed, failed, or canceled. Once in completed, failed, or canceled a member request will not move back to processing. The proper response from a failed member request, if not desired, would be to recreate the attempted changes in a new member request.
Renewal Readiness
Groups approaching open enrollment will typically contact the carrier directly to notify them of any new plans or group level modifications for their renewal period. Noyo will attempt to detect any changes in the carrier system and update our coverage records to match, but since those decisions are sent directly to the carrier, we may not know whether any changes found were intentional or whether additional updates are still in progress and need to complete before the carrier can accept member level open enrollment requests for the group.
The Renewal Readiness object allows you to tell us about the expected renewal changes for a group, so that Noyo can confirm when a carrier has installed everything correctly and is ready to receive member requests for the new plan year. A renewal decision record is defined by the target renewal date, and includes the lines of coverage and plans that are expected to be active for that renewal date. Noyo will then continuously check the carrier's system to confirm that your decisions have been processed. If expectations are met, we will update the status of the renewal readiness record to ready and you can start sending member requests. Otherwise, we will update the status to not_ready and inform you of any remaining issues.
Renewal Decision Statuses
Renewal decisions will move through several different statuses before and during open enrollment:
| Key | Description |
|---|---|
| submitted | This status is the result of the initial submission (POST). We have not yet verified the current state of the carrier’s system. |
| not_ready | There is a difference between your submitted renewal decision and the carrier's current state. We will supply an array of issues in a response body. |
| ready | Your renewal decision reflects what is shown in the carrier’s system. Open enrollment member requests will work as expected at this point. |
Renewal decisions will start with a submitted status, and then progress to ready or not_ready. The status can switch from ready to not_ready if we detect a carrier update that regresses their system to a state that is different from your decisions. The status can also switch from not_ready to ready if detected differences are resolved.
Get Renewal Decisions by Group
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/renewal_decisions
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
"version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
"created": 1557862286,
"modified": 1557862286,
"status": "not_ready",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
"name": "Select Plus PPO HDHP Gold BRJJ /C38"
},
{
"plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
"name": "Select Plus PPO HDHP Silver BRJJ /C38"
},
{
"plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
"name": "Select Plus PPO HDHP Bronze BRJJ /C38"
}
]
},
"dental": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "44bc0f4a-0a94-11ec-9a03-0242ac130003",
"name": "Dental Plus Plan"
}
]
}
}
}
]
},
"issues": [
{
"level": "error",
"message": "Life open enrollment start date is 2021-08-01 in carrier system"
},
{
"level": "error",
"message": "LTD Plan not available yet in carrier system"
}
]
}
]
}
Returns all renewal decisions for a group. This includes the status, which determines whether the carrier is ready to accept member requests for the new plan year. If the status is not_ready, Noyo will return one or more issues, each with a level and message.
Path Parameters
group_id |
The unique identifier of the group for which you are retrieving renewal decisions |
Query Parameters
renewal_date |
Renewal date to filter by, exact match |
Get Renewal Decisions by Group Response
meta* |
object |
|
response* |
array |
|
Get Renewal Decision by ID
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/renewal_decisions/4093a441-d4c8-4c8a-24d1-e7a132fb1bc2
Example Response
{
"id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
"version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
"created": 1557862286,
"modified": 1557862286,
"status": "not_ready",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
"name": "Select Plus PPO HDHP Gold BRJJ /C38"
},
{
"plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
"name": "Select Plus PPO HDHP Silver BRJJ /C38"
},
{
"plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
"name": "Select Plus PPO HDHP Bronze BRJJ /C38"
}
]
},
"dental": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "81803f12-0a96-11ec-9a03-0242ac130003",
"name": "Dental Plus Plan"
}
]
}
}
}
]
},
"issues": [
{
"level": "error",
"message": "Life open enrollment start date is 2021-08-01 in carrier system"
},
{
"level": "error",
"message": "LTD Plan not available yet in carrier system"
}
]
}
Returns a renewal decision by ID.
Path Parameters
group_id |
The unique identifier of the group for which you are retrieving a renewal decision |
renewal_decision_id |
The unique identifier of the renewal decision you want to retrieve |
Get Renewal Decisions by ID Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
status* |
string | Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted |
group_id* |
uuid | Unique identifier of the group in Noyo |
renewal_date* |
date | The start date for the new enrollment year when all coverage changes and decisions should become active |
body* |
object |
|
issues* |
array |
|
Create Renewal Decisions
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/renewal_decisions
Body Parameter
{
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "818e52d4-6c34-4914-b716-a3047c85e468"
},
{
"plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2"
},
{
"name": "Select Plus PPO HDHP Bronze BRJJ /C38"
}
]
},
"dental": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"name": "Dental Plus Plan"
}
]
}
}
}
]
}
}
Example Response
{
"id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
"version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
"created": 1557862286,
"modified": 1557862286,
"status": "submitted",
"group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
"name": "Select Plus PPO HDHP Gold BRJJ /C38"
},
{
"plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
"name": "Select Plus PPO HDHP Silver BRJJ /C38"
},
{
"plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
"name": "Select Plus PPO HDHP Bronze BRJJ /C38"
}
]
},
"dental": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "44bc0f4a-0a94-11ec-9a03-0242ac130003",
"name": "Dental Plus Plan"
}
]
}
}
}
]
},
"issues": []
}
Create a new renewal decision for a given renewal date.
Path Parameters
group_id |
The unique identifier of the group for which you are creating a new renewal decision |
Send Configurations
The renewal decision may be submitted in a few different configurations:
- With full data: each carrier can be configured with lines of coverage objects complete with open enrollment dates and plans
- With no lines of coverage at all: in this case, we will move the renewal decision to
readywhen we find any plans for this carrier on the renewal date in question. - Without open enrollment dates for each line of coverage: each carrier block would be submitted with lines of coverage, but only with plans underneath. This may be useful if you do not know what open enrollment dates to expect. In this case, only the plans will be compared within each carrier's lines of coverage.
Permitted Time Window
A renewal decision may be created with a renewal date up to 30 days ago, and up to 6 months in the future. Both of these constraints are relative to the date the request is sent.
Request Body
renewal_date* |
date | The start date for the new enrollment year when all coverages should be active |
body* |
object |
|
Create Renewal Decisions Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
status* |
string | Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted |
group_id* |
uuid | Unique identifier of the group in Noyo |
renewal_date* |
date | The start date for the new enrollment year when all coverage changes and decisions should become active |
body* |
object |
|
issues* |
array |
|
Edit Renewal Decisions
Code Sample
curl -X PUT
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/renewal_decisions/4093a441-d4c8-4c8a-24d1-e7a132fb1bc2/d012e6ac-05dd-4cbe-8666-940af78c9e56
Body Parameter
{
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "818e52d4-6c34-4914-b716-a3047c85e468"
},
{
"plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2"
},
{
"name": "Select Plus PPO HDHP Bronze BRJJ /C38"
}
]
},
"dental": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"name": "Dental Plus Plan"
}
]
}
}
}
]
}
}
Example Response
{
"id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
"version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
"created": 1557862286,
"modified": 1557862286,
"status": "submitted",
"group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
"name": "Select Plus PPO HDHP Gold BRJJ /C38"
},
{
"plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
"name": "Select Plus PPO HDHP Silver BRJJ /C38"
},
{
"plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
"name": "Select Plus PPO HDHP Bronze BRJJ /C38"
}
]
},
"dental": {
"open_enrollment_start_date": "2022-01-01",
"open_enrollment_end_date": "2022-01-31",
"plans": [
{
"plan_id": "44bc0f4a-0a94-11ec-9a03-0242ac130003",
"name": "Dental Plus Plan"
}
]
}
}
}
]
},
"issues": []
}
Edit an existing renewal decision for a group.
Path Parameters
renewal_decision_id |
The unique identifier of the renewal decision you want to edit |
version |
The unique identifier of the renewal decision version you want to edit |
Request Body
renewal_date |
date | The start date for the new enrollment year when all coverage changes and decisions should become active |
body |
object |
|
Edit Renewal Decisions Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
status* |
string | Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted |
group_id* |
uuid | Unique identifier of the group in Noyo |
renewal_date* |
date | The start date for the new enrollment year when all coverage changes and decisions should become active |
body* |
object |
|
issues* |
array |
|
Dropping Coverage
Use an empty object like the
dentalexample below on a POST or a PUT to drop coverage
{
"renewal_date": "2022-01-01",
"body": {
"carriers": [
{
"carrier_id": "4d4d815b-ae8f-430c-901f-1c9d5ee3f4f1",
"lines_of_coverage": {
"medical": {
"open_enrollment_start_date": "2021-07-01",
"open_enrollment_end_date": "2021-08-31",
"plans": [
{
"name": "Select Plus PPO HDHP Bronze BRJJ / C38"
}
]
}
}
},
{
"carrier_id": "6026ccdd-14e0-44dd-a68f-86b08cc89cf4",
"lines_of_coverage": {
"dental": {}
}
}
]
}
}
To confirm that coverage should be discontinued and no plans should be active for an upcoming renewal, you can pass an empty block for that carrier and line of coverage.
Also note that omitting a carrier from the request will mean that carrier is not evaluated for renewal readiness, and omitting a line of coverage for a carrier will mean that whether or not coverage is found would not impact the overall status or reported issues.
Based on this example request, we would evaluate renewal readiness for the group with the two provided carriers. We would expect one medical plan to be active at the first carrier and no dental coverage to be active at the second carrier, while the presence of any other lines of coverage at either carrier would be ignored.
Open Enrollment
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/open_enrollment
Body Parameter
{
"coverages": [
{
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"carrier_config": {},
"signature_date": "2022-01-15",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
}
}
]
}
Example Response
{
"id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "open_enrollment",
"status": "processing",
"transactions": [
"579952dd-9a66-4587-a4f7-72a63bf9ec86"
],
"body": {
"coverages": [
{
"carrier_config": {},
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
},
"signature_date": "2022-01-15"
}
]
}
}
The open enrollment member request is used to make changes to existing employees, dependents and coverages during the open enrollment period.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:
| Key | Description |
|---|---|
accident |
Accident |
add |
Accidental Death & Dismemberment |
cancer |
Cancer |
critical_illness |
Critical Illness |
dental |
Dental |
hospital_indemnity |
Hospital Indemnity |
life |
Life |
ltd |
Long Term Disability |
medical |
Medical |
std |
Short Term Disability |
vision |
Vision |
Signature Date
Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.
signature_date |
string | ISO-8601 date string for signature date |
Coverage Actions
Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.
Adding Coverage
The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier along with the plan_id. The plan_id can be retrieved by selecting a valid plan from the group plans list.
Adding medical, dental, vision, accident, cancer or hospital_indemnity coverage
Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
prior_coverage |
object |
|
Adding life, add, std, ltd and critical_illness coverage
Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
volumeˢ |
integer | Elected volume for the type of coverage being selected |
prior_coverage |
object |
|
Removing Coverage
The removing_coverage action is used to remove coverage from a member with a carrier. The structure of the removing_coverage action is below:
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member removing coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
reason* |
string | Reason the member is removing or canceling coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal |
Modifying Coverage
The modifying_coverage action is used to make changes to an existing coverage for a member / plan combination, given that the member already has coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or provide a new carrier_config to remain on the same plan but move the member into a new subgroup or benefit class.
Modifying medical, dental, vision, accident, cancer or hospital_indemnity coverage
Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member modifying coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
Modifying life, add, std, ltd and critical_illness coverage
Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member modifying coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
volumeˢ |
integer | Elected volume for the type of coverage being selected |
Open Enrollment Transactions
One or more open enrollment transactions will created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).
Open Enrollment Member Transaction completed Result
Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.
New Hire Enrollment
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/72af10df-a8b3-46f1-a114-ac36d4b8a6ea/member_requests/new_hire
Body Parameter
{
"coverages": [
{
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"carrier_config": {},
"signature_date": "2020-01-15",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
}
]
},
"vision": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}
]
}
}
}
]
}
Example Response
{
"id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
"employee_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"request_type": "new_hire",
"status": "processing",
"transactions": [
"a6e30204-87b2-4802-95a4-a156bd0f7435"
],
"body": {
"coverages": [
{
"carrier_config": {},
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
}
]
},
"vision": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}
]
}
},
"signature_date": "2020-01-15"
}
]
},
"result": {}
}
The new hire member request is used to add an existing employee, and optionally their dependents to multiple coverages at multiple carriers.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
Creating Employees and Dependents
Prior to adding an employee and dependent(s) to coverage, you should ensure they have been added to the API via the create employee and create dependent endpoints. Note: The hire_date of the employee will be sent to the carrier and the beginning of the coverage will be computed by the carrier according to the waiting period for the group.
The Coverages Object
The coverages array contains one entry for each carrier with which you would like to enroll or waive coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:
| Key | Description |
|---|---|
accident |
Accident |
add |
Accidental Death & Dismemberment |
cancer |
Cancer |
critical_illness |
Critical Illness |
dental |
Dental |
hospital_indemnity |
Hospital Indemnity |
life |
Life |
ltd |
Long Term Disability |
medical |
Medical |
std |
Short Term Disability |
vision |
Vision |
Signature Date
Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.
signature_date |
string | ISO-8601 date string for signature date |
Enrolling Members
You must provide an enrolling_members entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.
Enrolling in medical, dental, vision, accident, cancer or hospital_indemnity
Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
Enrolling in life, add, std, ltd or critical_illness
Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
volumeˢ |
integer | Elected volume for the type of coverage being selected |
Waiving Members
You can provide a waiving_members entry for each employee or dependent that is waiving coverage with the carrier along with the reason for waiving the coverage. This information will be communicated with the carrier where applicable. If you did not capture this information and only have the enrolling_members information the API request will still succeed.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member waiving coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
reason* |
string | Reason the member is waiving coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal |
New Hire Member Request Result
Sample Request Result
{
"dental": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}],
"vision": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}]
}
Upon the successful completion of all the transactions in the new hire member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:
member_id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member for the member enrollment result. One of: dependent, employee |
individual_enrollment_id* |
uuid | Unique identifier of the individual enrollment in Noyo created by the member request |
New Hire Transactions
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_transactions/a6e30204-87b2-4802-95a4-a156bd0f7435
Example Response
{
"id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
"member_request_id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
"employee_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": [
"dental",
"vision"
],
"status": "processing",
"type": "carrier_new_hire",
"body": {
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"dental": {
"enrolling_members": [{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
}, {
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
}]
},
"vision": {
"enrolling_members": [{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}, {
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}]
}
}
}
}
A new hire transaction is created for each entry in the coverages array (i.e. one transaction per carrier) with a type of carrier_new_hire.
New Hire Member Transaction completed Result
Upon the successful completion of the transaction, the status of the member transaction will be updated to completed and the result of the member transaction will be in the same format as the member request result
Qualifying Life Event
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/qualifying_life_event
Body Parameter
{
"event": {
"event_type": "newborn",
"event_date": "2020-01-01"
},
"coverages": [
{
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"carrier_config": {},
"signature_date": "2020-01-15",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
}
}
]
}
Example Response
{
"id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "qualifying_life_event",
"status": "processing",
"transactions": [
"579952dd-9a66-4587-a4f7-72a63bf9ec86"
],
"body": {
"coverages": [
{
"carrier_config": {},
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
},
"signature_date": "2020-01-15"
}
],
"event": {
"event_date": "2020-01-01",
"event_type": "newborn"
}
}
}
The qualifying life event member request is used to make changes to existing employees, dependents and coverages due to a qualifying life event.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
The Event Object
Each Qualifying Life Event requires an event parameter in the body which provides information about the type of the event as well as the date of its occurence. The schema for the event must follow this structure:
event_type* |
string | Qualifying life event type. One of: adoption, change_to_full_time, change_to_part_time, classifications_change, court_order, death, dependent_open_enrollment, divorce, foster_care, immigration_status_change, legal_guardian, lost_coverage, marriage, medicare, moved, newborn, offline_change, rate_changed, rehire, reinstatement |
event_date* |
string | ISO-8601 date string for qualifying life event date |
Event Types Available
| Value | Description |
|---|---|
adoption |
This applies in the event that a member is looking to either add or remove coverage as a result of an adoption. |
change_to_full_time |
This is often tied to benefit class or time status changes. |
change_to_part_time |
This is often tied to a reduction of hours or a benefit class change. |
court_order |
This is also sometimes known as QMCSO (qualified medical child support orders). |
death |
This is applicable to employee, child, or spouse deaths and can be passed when adding or removing coverage due to death. Sending this is useful clarification in survivorship scenarios. |
dependent_open_enrollment |
This refers to a case in which the dependent is removing themselves from another member's coverage and going through their own open enrollment. |
divorce |
This applies in the event that a member is looking to either add or remove coverage as a result of a divorce. |
foster_care |
This refers to a member adding a foster child to coverage. |
immigration_status_change |
This can refer to a case in which the spouse obtains a green card and is then added to member's coverage. |
legal_guardian |
This is applicable when a member becomes a legal guardian for a child and adds the child to coverage. |
lost_coverage |
This is a catch-all for when a member is losing coverage not due to any other QLEs mentioned above. This is applicable when adding someone to coverage due to lost coverage elsewhere and also when removing them from coverage. |
marriage |
This applies in the event that a member is looking to either add or remove coverage as a result of a marriage. |
medicare |
This is applicable when a member gains medicare coverage or when member loses medicare coverage. |
moved |
In this scenario, an address change makes someone either eligible or ineligible for coverage. |
newborn |
This applies in the event that a member is looking to either add or remove coverage as a result of the birth of a child. |
offline_change |
A change made outside of conventional open enrollment or special enrollment periods. |
rate_changed |
This refers to a specific case in which a rate changes after the employee elects coverage. Some benefits administration platforms allow the employee to reselect coverage if they are dissatisfied with the new rates in these cases. |
rehire |
Noyo currently makes no distinction between rehire and reinstatement cases. This code is applicable in both cases. |
reinstatement |
Coverage is being resumed after a gap. |
The QLE Coverages Object
The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:
| Key | Description |
|---|---|
accident |
Accident |
add |
Accidental Death & Dismemberment |
cancer |
Cancer |
critical_illness |
Critical Illness |
dental |
Dental |
hospital_indemnity |
Hospital Indemnity |
life |
Life |
ltd |
Long Term Disability |
medical |
Medical |
std |
Short Term Disability |
vision |
Vision |
Signature Date
Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.
signature_date |
string | ISO-8601 date string for signature date |
Coverage Actions
Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.
Adding Coverage
The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.
Adding medical, dental, vision, accident, cancer or hospital_indemnity coverage
Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
prior_coverage |
object |
|
Adding life, add, std, ltd or critical_illness coverage
Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
volumeˢ |
integer | Elected volume for the type of coverage being selected |
prior_coverage |
object |
|
Removing Coverage
The removing_coverage action is used to remove coverage from a member with a carrier. The structure of the removing_coverage action is below:
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member removing coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
reason* |
string | Reason the member is removing or canceling coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal |
Modifying Coverage
The modifying_coverage action is used to make changes to an existing coverage for a member / plan combination, given that the member already has coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or provide a new carrier_config to remain on the same plan but move the member into a new subgroup or benefit class.
Modifying medical, dental, vision, accident, cancer or hospital_indemnity coverage
Medical, dental, vision, accident, cancer and hospital_indemnity coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member modifying coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
Modifying life, add, std, ltd and critical_illness coverage
Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member modifying coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
volumeˢ |
integer | Elected volume for the type of coverage being selected |
Qualifying Life Event Member Request Result
Sample Request Result
{
"dental": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}],
"vision": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}]
}
Upon the successful completion of all the transactions in the qualifying life event member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:
member_id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member for the member enrollment result. One of: dependent, employee |
individual_enrollment_id* |
uuid | Unique identifier of the individual enrollment in Noyo created by the member request |
Qualifying Life Event Transactions
One or more qualifying life event transactions will created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).
Qualifying Life Event Member Transaction completed Result
Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.
Termination
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/6dc22bed-27fc-458c-b732-bdaf5b5a1031/member_requests/termination
Body Parameter
{
"reason": "voluntary",
"last_work_date": "2020-01-15",
"signature_date": "2020-01-01"
}
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"created": 1557512389,
"modified": 1564440756,
"employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
"request_type": "termination",
"status": "processing",
"transactions": [
"f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
],
"body": {
"employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
"last_work_date": "2020-01-15",
"reason": "voluntary",
"signature_date": "2020-01-01"
}
}
The termination member request is used to remove an employee and their dependents from coverage at all carriers. The last_work_date will be communicated to the carrier and the last_day_of_coverage will be determined by the carrier and included in the result.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
Body Parameters
The member request for termination is straightforward and requires the following parameters in the body:
reason* |
string | Reason for employee termination of coverage. One of: involuntary, job-eliminated, leave-of-absence, loss-of-eligibility, member-deceased, military-leave, voluntary |
last_work_date* |
string | ISO-8601 date string for last day of work of the terminated employee |
signature_date |
string | ISO-8601 date string for signature date |
Signature Date
Within the termination request body you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system to the carrier as the signature_date.
Termination Transactions
A termination transaction is created for each carrier that the employee and dependents have coverage with a type of carrier_termination. A transaction is also created with the type noyo_termination. The noyo_termination transaction will complete on the last_work_date and will update the Employee object to be marked as terminated along with information about the last day of employment.
Carrier Termination Result
The result of the carrier_termination member transaction will include the last day that the members are covered at the carrier. The individual enrollments for the carrier will also be updated with a new status of terminated.
Sample Transaction Result
{
"last_day_of_coverage": "2018-02-01"
}
Demographic Change
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/demographic
Body Parameter
{
"change_date": "2020-01-15",
"signature_date": "2020-01-15",
"member_changes": [
{
"member": {
"id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
"type": "employee"
},
"name_change": {
"first_name": "David",
"last_name": "Williamson"
},
"contact_change": {
"home_phone": "+15555551212",
"work_phone": "+15555551212",
"email_address": "david.williamson@example.com",
"email_address_type": "home"
},
"salary_change": {
"amount": 55000,
"unit": "annual",
"type": "salary"
}
}
]
}
Example Response
{
"id": "db6f362a-9f90-49b2-a73d-830cd2726537",
"created": 1557512389,
"modified": 1564440756,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "demographic",
"status": "processing",
"transactions": [
"b56bfe70-2632-49e9-b269-1eaa36ed7fd6"
],
"body": {
"change_date": "2020-01-15",
"member_changes": [
{
"contact_change": {
"email_address": "david.williamson@example.com",
"email_address_type": "home",
"home_phone": "+15555551212",
"work_phone": "+15555551212"
},
"member": {
"id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
"member_type": "employee"
},
"name_change": {
"first_name": "David",
"last_name": "Williamson"
},
"salary_change": {
"amount": 55000,
"type": "salary",
"unit": "annual"
}
}
],
"signature_date": "2020-01-15"
}
}
The demographic change member request is used to update information such as name, address, and salary for one or many members. The updates will be carried out for each carrier that has a record of each member.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
Demographic Change Member Request Body
change_date |
string | ISO-8601 date string for effective date of demographic change |
signature_date |
string | ISO-8601 date string for signature date |
member_changes* |
array |
|
Demographic Change Member Request Result
Sample Request Result
[{
"id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
"type" "employee",
"version": "cf78e9b2-6213-448b-a0b9-04a254a84872"
}]
Upon the successful completion of all the transactions in the demographic change member request, the status of the member request will be updated to completed and the result of the member request will be an object containing an array of updated members. The employee and dependent objects in the Noyo API will be updated only when all transactions have completed.
COBRA Enrollment
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/72af10df-a8b3-46f1-a114-ac36d4b8a6ea/member_requests/cobra_enrollment
Body Parameter
{
"termination_info": {
"reason": "voluntary",
"last_work_date": "2020-01-01"
},
"coverages": [
{
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"carrier_config": {},
"signature_date": "2020-01-15",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
}
]
},
"vision": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}
]
}
}
}
]
}
Example Response
{
"id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
"created": 1557512389,
"modified": 1564440756,
"employee_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"request_type": "cobra_enrollment",
"status": "processing",
"transactions": [
"a6e30204-87b2-4802-95a4-a156bd0f7435"
],
"body": {
"coverages": [
{
"carrier_config": {},
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
}
]
},
"vision": {
"enrolling_members": [
{
"id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
},
{
"id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}
]
}
},
"signature_date": "2020-01-15"
}
],
"termination_info": {
"last_work_date": "2020-01-01",
"reason": "voluntary"
}
},
"result": {}
}
The COBRA enrollment member request is used to add an existing employee, and optionally their dependents to multiple coverages at multiple carriers. This is for a continuation of benefits situation, when main line coverage either has already been terminated, or will be in conjunction with this member request.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
Termination Info
The termination_info block contains information about the termination of the employee prior to COBRA enrollment. If you have already sent a Termination Member Request for the employee the data from that request will be used. If you have not sent a Termination Member Request the data from this request will be used to terminate the member at the carrier.
reason* |
string | Reason for employee termination of coverage. One of: involuntary, job-eliminated, leave-of-absence, loss-of-eligibility, member-deceased, military-leave, voluntary |
last_work_date* |
string | ISO-8601 date string for last day of work of the terminated employee |
The Coverages Object
The coverages array contains one entry for each carrier with which you would like to enroll or waive coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:
| Key | Description |
|---|---|
accident |
Accident |
add |
Accidental Death & Dismemberment |
cancer |
Cancer |
critical_illness |
Critical Illness |
dental |
Dental |
hospital_indemnity |
Hospital Indemnity |
life |
Life |
ltd |
Long Term Disability |
medical |
Medical |
std |
Short Term Disability |
vision |
Vision |
Signature Date
Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.
signature_date |
string | ISO-8601 date string for signature date |
Enrolling Members
You must provide an enrolling_members entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.
Enrolling in medical, dental, vision, accident, cancer or hospital_indemnity
Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
Enrolling in life, add, std, ltd or critical_illness
Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
volumeˢ |
integer | Elected volume for the type of coverage being selected |
Waiving Members
You can provide a waiving_members entry for each employee or dependent that is waiving coverage with the carrier along with the reason for waiving the coverage. This information will be communicated with the carrier where applicable. If you did not capture this information and only have the enrolling_members information the API request will still succeed.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member waiving coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
reason* |
string | Reason the member is waiving coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal |
Sample Request Result
{
"dental": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}],
"vision": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}]
}
Upon the successful completion of all the transactions in the member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:
member_id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member for the member enrollment result. One of: dependent, employee |
individual_enrollment_id* |
uuid | Unique identifier of the individual enrollment in Noyo created by the member request |
COBRA Open Enrollment
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/cobra_open_enrollment
Body Parameter
{
"coverages": [
{
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"carrier_config": {},
"signature_date": "2021-01-15",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
}
}
]
}
Example Response
{
"id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
"created": 1557512389,
"modified": 1564440756,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "cobra_open_enrollment",
"status": "processing",
"transactions": [
"579952dd-9a66-4587-a4f7-72a63bf9ec86"
],
"body": {
"coverages": [
{
"carrier_config": {},
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
},
"signature_date": "2021-01-15"
}
]
}
}
The COBRA open enrollment member request is used to make changes to employees, dependents and COBRA coverages during the open enrollment period.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys for COBRA open enrollment:
| Key | Description |
|---|---|
dental |
Dental |
medical |
Medical |
vision |
Vision |
Signature Date
Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.
signature_date |
string | ISO-8601 date string for signature date |
Coverage Actions
Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.
Adding Coverage
The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier along with the COBRA eligible plan_id. The plan_id can be retrieved by selecting a valid plan from the group plans list.
Adding medical, dental, or vision coverage
Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
prior_coverage |
object |
|
Removing Coverage
The removing_coverage action is used to remove coverage from a member with a carrier. The structure of the removing_coverage action is below:
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member removing coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
reason* |
string | Reason the member is removing or canceling coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal |
Modifying Coverage
The modifying_coverage action is used to make changes to an existing coverage for a COBRA enrolled member / plan combination, given that the member already has COBRA coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or pass the same set of plans to remain on COBRA coverage with no changes.
Modifying medical, dental, or vision coverage
Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member modifying coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
COBRA Open Enrollment Transactions
One or more COBRA open enrollment transactions will created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).
COBRA Open Enrollment Member Transaction completed Result
Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.
COBRA Qualifying Life Event
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/cobra_qualifying_life_event
Body Parameter
{
"event": {
"event_date": "2021-01-01",
"event_type": "newborn"
},
"coverages": [
{
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"carrier_config": {},
"signature_date": "2021-01-15",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
}
}
]
}
Example Response
{
"id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
"created": 1557512389,
"modified": 1564440756,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "cobra_qualifying_life_event",
"status": "processing",
"transactions": [
"579952dd-9a66-4587-a4f7-72a63bf9ec86"
],
"body": {
"coverages": [
{
"carrier_config": {},
"carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
"lines_of_coverage": {
"medical": {
"adding_coverage": [
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"member_type": "dependent",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
}
]
}
},
"signature_date": "2021-01-15"
}
],
"event": {
"event_date": "2021-01-01",
"event_type": "newborn"
}
}
}
The COBRA qualifying life event member request is used to make changes to employees, dependents and COBRA coverages due to a qualifying life event.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
The Event Object
Each COBRA Qualifying Life Event requires an event parameter in the body which provides information about the type of the event as well as the date of its occurrence. The schema for the event must follow this structure:
event_type* |
string | Qualifying life event type. One of: adoption, change_to_full_time, change_to_part_time, classifications_change, court_order, death, dependent_open_enrollment, divorce, foster_care, immigration_status_change, legal_guardian, lost_coverage, marriage, medicare, moved, newborn, offline_change, rate_changed, rehire, reinstatement, terminate_cobra |
event_date* |
string | ISO-8601 date string for qualifying life event date |
The COBRA QLE Coverages Object
The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. For COBRA QLE requests, the lines_of_coverage object allows the following keys:
| Key | Description |
|---|---|
dental |
Dental |
medical |
Medical |
vision |
Vision |
Signature Date
Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.
signature_date |
string | ISO-8601 date string for signature date |
Coverage Actions
Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.
Adding Coverage
The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the COBRA eligible plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.
Adding medical, dental, or vision coverage
Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member adding coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
prior_coverage |
object |
|
Removing Coverage
The removing_coverage action is used to remove coverage from a member with a carrier. The structure of the removing_coverage action is below:
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member removing coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
reason* |
string | Reason the member is removing or canceling coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal |
Modifying Coverage
The modifying_coverage action is used to make changes to an existing coverage for a COBRA enrolled member / plan combination, given that the member already has COBRA coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or pass the same set of plans to remain on COBRA coverage with no changes.
Modifying medical, dental, or vision coverage
Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.
id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member modifying coverage. One of: dependent, employee |
plan_id |
uuid | Unique identifier of the group plan in Noyo |
COBRA Qualifying Life Event Member Request Result
Sample Request Result
{
"dental": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
}],
"vision": [{
"member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
"member_type": "employee",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}, {
"member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
"member_type": "dependent",
"individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
}]
}
Upon the successful completion of all the transactions in the COBRA qualifying life event member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:
member_id* |
uuid | Unique identifier of the employee or dependent in Noyo |
member_type* |
string | Type of member for the member enrollment result. One of: dependent, employee |
individual_enrollment_id* |
uuid | Unique identifier of the individual enrollment in Noyo created by the member request |
COBRA Qualifying Life Event Transactions
One or more COBRA qualifying life event transactions will be created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).
COBRA Qualifying Life Event Member Transaction completed Result
Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.
COBRA Termination
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/6dc22bed-27fc-458c-b732-bdaf5b5a1031/member_requests/cobra_termination
Body Parameter
{
"reason": "voluntary",
"cobra_termination_date": "2021-01-15",
"signature_date": "2021-01-01"
}
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"created": 1557512389,
"modified": 1564440756,
"employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
"request_type": "cobra_termination",
"status": "processing",
"transactions": [
"f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
],
"body": {
"cobra_termination_date": "2021-01-15",
"reason": "voluntary",
"signature_date": "2021-01-01"
}
}
The COBRA termination member request is used to remove an employee and their dependents from COBRA coverage at all carriers. The cobra_termination_date is the date on which the COBRA coverage should be terminated.
Path Parameters
employee_id |
The unique identifier of the employee related to the member request |
Body Parameters
The member request for COBRA termination is straightforward and requires the following parameters in the body:
reason* |
string | Reason the member has removed or canceled COBRA coverage. One of: expiration, involuntary, medicare-entitlement, new-enrollment, non-payment, voluntary |
cobra_termination_date* |
string | The COBRA Termination event date. |
signature_date |
string | ISO-8601 date string for signature date |
Signature Date
Within the COBRA termination request body you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system to the carrier as the signature_date.
COBRA Termination Transactions
A COBRA termination transaction is created for each carrier that the employee and dependents have coverage with a type of carrier_cobra_termination.
Carrier COBRA Termination Result
The result of the carrier_cobra_termination member transaction will include the last day that the members are covered at the carrier. The individual enrollments for the carrier will also be updated with a new status of terminated.
Sample Transaction Result
{
"last_day_of_coverage": "2018-02-01"
}
Member Premiums
Returns a premium amount billed to members for coverage with a carrier.
Premium Breakdown
Callers can query the API by employee ID to retrieve a list of member premiums associated with an employee and their family unit. The size of the response list will depend on the granularity of data made available by the carrier.
For example, if an employee is enrolled in dental and vision coverage and we know the exact cost split between each line of coverage, the response list would contain two member premium records, one with the dental amount and a single billed_members entry for the employee + dental plan, and one with the vision amount and a single billed_members entry for the employee + vision plan.
On the other hand, if we only know the total combined cost for both coverages, the response list would contain one member premium record with the total amount and two billed_members entries, one for the employee + dental plan and one for the employee + vision plan.
By Employee
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/premiums
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"carrier_id": "e2c76400-b505-432a-a1c1-c777bcec4648",
"amount": "50.00",
"period": {
"amount": 1,
"unit": "month"
},
"premium_type": "employer_amount",
"effective_start_date": "2020-01-01",
"effective_end_date": "2020-12-31",
"billed_members": [
{
"member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
"member_type": "employee",
"line_of_coverage": "dental",
"plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
},
{
"member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
"member_type": "employee",
"line_of_coverage": "vision",
"plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
},
{
"member_id": "67309c4b-12f5-4bb0-92ce-a45639af9055",
"member_type": "dependent",
"line_of_coverage": "dental",
"plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
},
{
"member_id": "8f5aaf65-c4e6-4909-9ebf-58b320645df2",
"member_type": "dependent",
"line_of_coverage": "vision",
"plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
}
],
"created": 1599184829,
"modified": 1599292817
},
{
"carrier_id": "e2c76400-b505-432a-a1c1-c777bcec4648",
"amount": "50.00",
"period": {
"amount": 1,
"unit": "month"
},
"premium_type": "employee_amount",
"effective_start_date": "2020-01-01",
"effective_end_date": "2020-12-31",
"billed_members": [
{
"member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
"member_type": "employee",
"line_of_coverage": "dental",
"plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
},
{
"member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
"member_type": "employee",
"line_of_coverage": "vision",
"plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
},
{
"member_id": "67309c4b-12f5-4bb0-92ce-a45639af9055",
"member_type": "dependent",
"line_of_coverage": "dental",
"plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
},
{
"member_id": "8f5aaf65-c4e6-4909-9ebf-58b320645df2",
"member_type": "dependent",
"line_of_coverage": "vision",
"plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
}
],
"created": 1599184829,
"modified": 1599292817
}
]
}
Returns list of Member Premium information for an employee and dependents
Path Parameters
employee_id |
Unique ID of the employee in Noyo |
Query Parameters
effective_date |
The relative date on which to view the state of the records. Defaults to today |
Member Premium List
meta* |
object |
|
response* |
array |
|
Verified Member Transactions
Often member transactions are sent in advance and will become effective at a date in the future (e.g, a new_hire member request with a hire_date of today, but the coverage does not start until the first of next month). Noyo works with carriers to verify that transactions have taken effect as expected and will mark the member transaction as verified when applicable. The verified field is the Unix time at which the member transaction was verified. You can expect the following timelines for verification at most carriers:
| Transaction Type | Timeline |
|---|---|
| New Hire | On or shortly after the effective_start_date of the created individual enrollments |
| Termination | On or shortly after the last_day_of_coverage |
| Qualifying Life Event | On or shortly after the effective date of coverage changes |
| Open Enrollment | On or shortly after the effective date of coverage changes |
| Demographic Change | Immediately after completion of the member transaction |
Member transactions and requests in the completed status require no additional attention or action from you. Think of verified transactions as ones where we were able to do a successful double check that everything went as we expected.
Note: There may be some cases where the carrier does not support verification. If the carrier supports verification and the member transaction does not verify in a timely manner we will notify you.
Getting Member Requests
Get Single Member Request
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_requests/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"created": 1557512389,
"completed": 1557565200,
"modified": 1557565200,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "termination",
"status": "processing",
"transactions": [
"f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
],
"body": {
"employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
"last_work_date": "2018-01-15",
"reason": "voluntary"
}
}
Returns the latest version of a single member request based on the ID provided.
Path Parameters
request_id |
The unique identifier of the member request you would like to view |
Get Single Member Request Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
completed |
timestamp | Timestamp indicating when a member request was marked as completed |
modified* |
timestamp | The date the record was last updated |
employee_id* |
uuid | Unique identifier of the employee in Noyo |
request_type* |
string | Transaction type for the member request. One of: cobra_enrollment, cobra_open_enrollment, cobra_qualifying_life_event, cobra_termination, demographic, enrollment_snapshot, new_hire, open_enrollment, qualifying_life_event, termination |
status* |
string | Status of the member request. One of: canceled, completed, failed, processing |
transactions |
array | List of unique identifiers of all associated member transactions in Noyo |
body* |
object | Data required to execute a member request, varies depending on the request type |
result* |
object | Result from executing the member request, varies depending on the request type |
For more information about the body and result fields check out the request-specific documentation
Get Member Requests for Employee
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
"created": 1557512389,
"completed": 1557565200,
"modified": 1557565200,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "new_hire",
"status": "processing",
"transactions": [
"a6e30204-87b2-4802-95a4-a156bd0f7435"
],
"body": {
"coverages": [
{
"carrier_config": {
"bill_group": "1000001",
"member_group": "99999"
},
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"lines_of_coverage": {
"dental": {
"waiving_members": [
{
"id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
"member_type": "employee",
"reason": "other-spouse-group"
}
]
}
}
}
]
}
},
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"created": 1557512394,
"completed": 1557565200,
"modified": 1557565200,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "termination",
"status": "processing",
"transactions": [
"f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
],
"body": {
"employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
"last_work_date": "2018-01-15",
"reason": "voluntary"
}
}
]
}
Returns a list of all member requests for a given employee. Each member request may have one or more associated member transactions.
Path Parameters
employee_id |
The unique identifier of the employee for which you would like to view member requests |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get All Member Requests
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_requests
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
"created": 1557512389,
"completed": 1557565200,
"modified": 1557565200,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "new_hire",
"status": "processing",
"transactions": [
"a6e30204-87b2-4802-95a4-a156bd0f7435"
],
"body": {
"coverages": [
{
"carrier_config": {
"bill_group": "1000001",
"member_group": "99999"
},
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"lines_of_coverage": {
"dental": {
"waiving_members": [
{
"id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
"member_type": "employee",
"reason": "other-spouse-group"
}
]
}
}
}
]
}
},
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"created": 1557512389,
"completed": 1557565200,
"modified": 1557565200,
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "termination",
"status": "processing",
"transactions": [
"f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
],
"body": {
"employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
"last_work_date": "2018-01-15",
"reason": "voluntary"
}
}
]
}
Returns a list of all member requests for a given organization. Each member request may have one or more associated member transactions.
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
employee_id |
Unique identifier of the employee in Noyo for which you would like to filter |
status |
The member request status for which you would like to filter |
request_type |
The member request type for which you would like to filter |
Get All Member Requests Response
meta* |
object |
|
response* |
array |
|
Filtering Member Requests
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_requests?status=processing&request_type=new_hire
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"request_type": "new_hire",
"status": "processing",
"transactions": [
"a6e30204-87b2-4802-95a4-a156bd0f7435"
],
"body": {
"coverages": [
{
"carrier_config": {
"bill_group": "1000001",
"member_group": "99999"
},
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"lines_of_coverage": {
"dental": {
"waiving_members": [
{
"id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
"member_type": "employee",
"reason": "other-spouse-group"
}
]
}
}
}
]
}
}
]
}
For cases where you would like to filter the Member Requests for you organization, you can do so by passing in one or more of the filters below into the query string.
employee_id |
uuid | Unique identifier of the employee in Noyo to be filtered on |
group_id |
uuid | Unique identifier of the group in Noyo to be filtered on |
status |
string | Status of the member request to be filtered on. One of: canceled, completed, failed, processing |
request_type |
string | Member request type to be filtered on. One of: cobra_enrollment, cobra_open_enrollment, cobra_qualifying_life_event, cobra_termination, demographic, enrollment_snapshot, new_hire, open_enrollment, qualifying_life_event, termination |
Getting Member Transactions
Get Single Member Transaction
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_transactions/a6e30204-87b2-4802-95a4-a156bd0f7435
Example Response
{
"id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
"created": 1557512389,
"modified": 1564440756,
"member_request_id": "bba6ea27-4004-4a52-a3d9-f986ace0d3da",
"employee_id": "25434576-e85d-481b-a825-962fd575046f",
"carrier_id": "478e066e-9696-490e-b60f-47f40c96dc7c",
"lines_of_coverage": [
"medical",
"dental",
"vision"
],
"status": "processing",
"body": {
"coverages": [
{
"carrier_config": {
"bill_group": "1000001",
"member_group": "99999"
},
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "2e6a04b6-21f3-40d7-a9e2-735196cc451b"
}
],
"waiving_members": []
},
"medical": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "1873df52-c9e9-4e3a-995c-f47f32d0bd62"
}
],
"waiving_members": []
},
"vision": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "9cb64800-022e-40af-ab80-8d945e430592"
}
],
"waiving_members": []
}
}
}
]
}
}
Returns the latest version of a single member transaction based on the ID provided.
Path Parameters
transaction_id |
The unique identifier of the member transaction you would like to view |
Get Single Member Transaction Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
member_request_id* |
uuid | Unique identifier of the member request in the Noyo system |
employee_id* |
uuid | Unique identifier of the associated employee in the Noyo system |
carrier_id |
uuid | Unique identifier of the carrier in the Noyo system |
lines_of_coverage* |
array | List of lines of coverage for the member transaction. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision |
transaction_type* |
string | Transaction type of the member transaction. One of: carrier_cobra_enrollment, carrier_cobra_open_enrollment, carrier_cobra_qualifying_life_event, carrier_cobra_termination, carrier_demographic, carrier_demographic_full, carrier_enrollment_snapshot_new_hire, carrier_new_hire, carrier_open_enrollment_adding, carrier_open_enrollment_full, carrier_open_enrollment_modifying, carrier_open_enrollment_removing, carrier_qualifying_life_event_adding, carrier_qualifying_life_event_full, carrier_qualifying_life_event_modifying, carrier_qualifying_life_event_removing, carrier_termination, noyo_termination |
status* |
string | Status of the member transaction. One of: canceled, completed, failed, processing |
verified |
timestamp | The date the member transaction was verified |
body* |
object | Body of the member transaction |
result* |
object | Result of the member transaction |
For more information about the body and result fields check out the request-specific documentation
Get Transactions for Request
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_requests/a6e30204-87b2-4802-95a4-a156bd0f7435/member_transactions
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
"created": 1557512389,
"modified": 1564440756,
"member_request_id": "bba6ea27-4004-4a52-a3d9-f986ace0d3da",
"employee_id": "25434576-e85d-481b-a825-962fd575046f",
"carrier_id": "478e066e-9696-490e-b60f-47f40c96dc7c",
"lines_of_coverage": [
"medical",
"dental",
"vision"
],
"status": "processing",
"body": {
"coverages": [
{
"carrier_config": {
"bill_group": "1000001",
"member_group": "99999"
},
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "2e6a04b6-21f3-40d7-a9e2-735196cc451b"
}
],
"waiving_members": []
},
"medical": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "1873df52-c9e9-4e3a-995c-f47f32d0bd62"
}
],
"waiving_members": []
},
"vision": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "9cb64800-022e-40af-ab80-8d945e430592"
}
],
"waiving_members": []
}
}
}
]
}
}
]
}
Returns a list of all member transactions for a given member request.
Path Parameters
request_id |
The unique identifier of the member request for which you would like to view member transaction |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get All Member Transactions
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/member_transactions
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
"created": 1557512389,
"modified": 1564440756,
"member_request_id": "bba6ea27-4004-4a52-a3d9-f986ace0d3da",
"employee_id": "25434576-e85d-481b-a825-962fd575046f",
"carrier_id": "478e066e-9696-490e-b60f-47f40c96dc7c",
"lines_of_coverage": [
"medical",
"dental",
"vision"
],
"status": "processing",
"body": {
"coverages": [
{
"carrier_config": {
"bill_group": "1000001",
"member_group": "99999"
},
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"lines_of_coverage": {
"dental": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "2e6a04b6-21f3-40d7-a9e2-735196cc451b"
}
],
"waiving_members": []
},
"medical": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "1873df52-c9e9-4e3a-995c-f47f32d0bd62"
}
],
"waiving_members": []
},
"vision": {
"enrolling_members": [
{
"id": "25434576-e85d-481b-a825-962fd575046f",
"member_type": "employee",
"plan_id": "9cb64800-022e-40af-ab80-8d945e430592"
}
],
"waiving_members": []
}
}
}
]
}
}
]
}
Returns a list of all member transactions
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
ids |
Comma-separated member transaction IDs you would like to view |
Get All Member Transactions Response
meta* |
object |
|
response* |
array |
|
Groups
This object represents an insured group underneath your organization. You can retrieve it to view details such as the name of the group and the SIC code of the company.
Get Single Group
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9
Example Response
{
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"version": "6b72d72d-cc99-4df6-8152-7183e824c80c",
"created": 1557512389,
"modified": 1543215342,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"name": "Test Company",
"sic_code": "7371",
"dba_name": "Test Corp",
"federal_ein": "112222222"
}
Returns the latest version of a single group based on the ID provided.
Path Parameters
group_id |
The unique identifier of the group to be retrieved |
Get Single Group Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
organization_id* |
uuid | Unique identifier of the platform or broker organization in Noyo |
name* |
string | Name of the group |
sic_code |
string | SIC Code of the group |
dba_name |
string | DBA name for the company, if applicable |
federal_ein |
string | Federal Employer Identification Number for the company |
Get Groups
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"version": "6b72d72d-cc99-4df6-8152-7183e824c80c",
"created": 1557512389,
"modified": 1543215342,
"organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
"name": "Test Company",
"sic_code": "7371",
"dba_name": "Test Corp",
"federal_ein": "112222222"
}
]
}
Returns a list of all groups in the current user organization.
If you would like to search the groups list, you can use the company query param. It allows searches based on the group's name or dba_name values.
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
company |
This query param searches groups by name or dba_name values |
group_ids |
Comma-separated list of requested UUID group IDs |
carrier_id |
Used for filtering for a carrier-specific group ID. Filter by the Noyo carrier ID. Must be used with carrier_group_id |
carrier_group_id |
Used for filtering for a carrier-specific group ID. Must be used with carrier_id |
Filter for a carrier group ID
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups?carrier_id=3092866a-e3a7-4c6e-964c-2bc45dfe7ad0&carrier_group_id=OXNEMWQ4WkxoQ0oK
You can use the combination of a carrier_id and a carrier_group_id to filter for a carrier-specific group ID. This ID will depend on the carrier, but it will generally be a unique identifier for the group from the carrier's system.
Get Groups Response
meta* |
object |
|
response* |
array |
|
Get Group Carrier Configurations
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2705bb9f-3c90-4400-a4e7-0bc9d48e677c/carrier_configurations
Example Response
[
{
"group_id": "2705bb9f-3c90-4400-a4e7-0bc9d48e677c",
"carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
"carrier_group_id": "9100084",
"configuration": {
"bill_groups": [
{
"bill_group_description": "All Members",
"bill_group_number": 10001,
"bill_group_status": "open"
}
],
"member_groups": [
{
"member_group_key": 2613038,
"member_group_name": "MEMBERS A",
"member_group_status": "open"
},
{
"member_group_key": 2613037,
"member_group_name": "MEMBERS B",
"member_group_status": "open"
}
],
"policy_number": "9100084"
}
}
]
Certain carriers have custom data for each group such as billing group information. This endpoint can be used to retrieve carrier-specific configuration data.
Path Parameters
group_id |
The unique identifier of the group for which you would like to view carrier configurations. |
Query Parameters
effective_date |
The relative date on which to view the state of the record |
Group Carrier Configuration Object
group_id* |
uuid | Unique identifier of the group in Noyo |
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
carrier_group_id* |
string | Unique identifier for the group in the carrier system |
configuration* |
object | Carrier configuration details for the group |
Get Single Contact
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts/30b74a44-d5b1-4123-a7a4-6d3aec251ba4
Example Response
{
"id": "c2f5489d-36d1-4fb0-bf9f-105ad5dd0b3e",
"version": "ef3fef8d-4889-40f4-a0f8-377b9dd23d98",
"created": 1557512389,
"modified": 1543215342,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"first_name": "David",
"last_name": "Smith",
"title": "Chief People Officer",
"email": "davidsmith@testcorp.com",
"phone_number": "+14255551234",
"types": [
"company",
"billing",
"executive"
],
"primary_contact": true
}
Returns the latest version of a single group contact based on the ID provided.
Path Parameters
group_id |
The unique identifier of the group the contact belongs to |
contact_id |
The unique identifier of the contact to be retrieved |
Get Single Contact Response
id* |
uuid | Unique identifier of the group contact in Noyo |
version* |
uuid | Version of the group contact record |
created* |
timestamp | The date the record was originated |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
first_name |
string | First name of the group contact |
last_name |
string | Last name of the group contact |
title |
string | Job title of the group contact |
email |
string | Work email address of the group contact |
phone_number |
string | Work phone number of the group contact in E.164 format |
types* |
array | List of contact types for the group contact. One of: billing, company, executive, online |
primary_contact |
boolean | True if contact is the primary contact for the group |
Get Contacts
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"id": "c2f5489d-36d1-4fb0-bf9f-105ad5dd0b3e",
"version": "6ba43c6e-69f2-435f-a126-8595a798eb52",
"created": 1557512389,
"modified": 1543215342,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"first_name": "David",
"last_name": "Smith",
"title": "Chief People Officer",
"email": "davidsmith@testcorp.com",
"phone_number": "+14255551234",
"types": [
"company",
"billing"
],
"primary_contact": true
},
{
"id": "7e3c1f14-e7e7-42b8-81d8-3fcd7bd7d418",
"version": "88bfbe28-7f8b-4497-a50b-932ee3387b68",
"created": 1557512389,
"modified": 1543215342,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"first_name": "Caroline",
"last_name": "Johnson",
"title": "VP of Human Resources",
"email": "carolinejohnson@testcorp.com",
"phone_number": "+14255551234",
"types": [
"executive"
],
"primary_contact": false
}
]
}
Returns a list of all group contacts for a given group.
Path Parameters
group_id |
The unique identifier of the group for which you would like to view contacts |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get Contacts Response
meta* |
object |
|
response* |
array |
|
Get Single Location
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations/bd957820-4652-4ee7-8a3a-6413df21e28d
Example Response
{
"id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
"created": 1557512389,
"modified": 1543215342,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"address": {
"street_one": "1234 Test Ln",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
}
}
Returns the latest version of a single group location based on the ID provided.
Path Parameters
group_id |
The unique identifier of the group the location belongs to |
location_id |
The unique identifier of the location to be retrieved |
Single Location Response
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
display_name* |
string | Display name for the group location |
address* |
object |
|
Get Locations
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
"created": 1557512389,
"modified": 1543215342,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"address": {
"street_one": "1234 Test Ln",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
}
}
]
}
Returns a list of all group locations for a given group.
Path Parameters
group_id |
The unique identifier of the group for which you would like to view locations |
Query Parameters
page_size |
The max size of each page of results |
offset |
The integer offset at which to start the page. Possible values are 0 to total_records - 1 |
Get Locations Response
meta* |
object |
|
response* |
array |
|
Get Latest Audit
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/groups/2ce3b54a-2535-4803-b218-e6b44081d418/audit_requests/latest
Example Response
{
"group_id": "2ce3b54a-2535-4803-b218-e6b44081d418",
"carrier_ids": [
"8fac0992-933a-4743-8dab-0d606ef2569e"
],
"completed_at": 1602609543
}
Noyo regularly audits each Group against the carrier(s) that the Group has coverage with in order to find updated data and potential mismatches. This endpoint returns metadata about the latest group audit request that was completed. If no group audits have been completed the completed_at timestamp will be the timestamp of when the group was created and the carrier_ids array will be empty.
Path Parameters
group_id |
The unique identifier of the associated group in Noyo |
Query Parameters
carrier_id |
The unique identifier of the carrier for which you would like to view audit requests |
Get Latest Audit Response
group_id* |
uuid | Unique identifier of the associated group in Noyo |
carrier_ids* |
array | List of carrier IDs included in group audit |
completed_at* |
timestamp | The date the group audit request was completed |
Employees
This object represents an employee within a group. It contains personal information about the employee including name, address, contact info, etc. as well as employment related information like salary, occupation and employment status.
Create Employee
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyo.com/api/v1/employees
Body Parameter
{
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"location_id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"person": {
"first_name": "David",
"last_name": "Johnson",
"home_address": {
"street_one": "1234 Home Ave",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
},
"date_of_birth": "1981-06-22",
"ssn": "123456789",
"sex": "M",
"marital_status": "married",
"contact": {
"home_phone": "+12065551234",
"work_phone": "+12065559876",
"email_address": "david@testemail.com",
"email_address_type": "home",
"preferred_method": "email"
}
},
"employment": {
"employment_status": "full-time",
"occupation": "Senior Analyst",
"hours_worked": 50,
"salary": {
"amount": 55000,
"unit": "annual",
"type": "salary"
},
"employment_dates": {
"hire_date": "2014-12-10",
"full_time_start": "2015-01-01"
}
},
"classifications": {
"BranchName": "HQ"
}
}
Example Response
{
"id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
"created": 1626281253,
"modified": 1626281253,
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"location_id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
"person": {
"first_name": "David",
"last_name": "Johnson",
"home_address": {
"street_one": "1234 Home Ave",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
},
"date_of_birth": "1981-06-22",
"ssn": "123456789",
"sex": "M",
"marital_status": "married",
"contact": {
"home_phone": "+12065551234",
"work_phone": "+12065559876",
"email_address": "david@testemail.com",
"email_address_type": "home",
"preferred_method": "email"
}
},
"employment": {
"employment_status": "full-time",
"occupation": "Senior Analyst",
"hours_worked": 50,
"salary": {
"amount": 55000,
"unit": "annual",
"type": "salary"
},
"employment_dates": {
"hire_date": "2014-12-10",
"full_time_start": "2015-01-01"
}
},
"classifications": {
"BranchName": "HQ"
}
}
Create a new employee for a group.
Request Body
group_id* |
uuid | Unique identifier of the group in Noyo |
location_id |
uuid | Unique identifier of the employee group location in Noyo |
person* |
object |
|
employment* |
object |
|
classifications |
object | Fields that classify employees for group structure mapping |
Create Employee Response
id* |
uuid | Unique identifier of the employee in Noyo |
custom_individual_id |
string | The custom identifier for this employee in your system |
version* |
uuid | Version of the employee record |
created* |
timestamp | The date the record was originated |
modified* |
timestamp | The date the record was last updated |
group_id* |
uuid | Unique identifier of the group in Noyo |
location_id |
uuid | Unique identifier of the employee group location in Noyo |
person* |
object |
|
employment* |
object |
|