Noyo Fulfillment API v1.0.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Welcome to Noyo's API! Noyo's API enables you to execute, track, and confirm the fulfillment of member transaction requests to carriers.
This guide intends to help you noyo (see what we did there?) way around carrier fulfillment.
The following member request types are currently supported:
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.noyoconnect.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.noyoconnect.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 the Fulfillment API to aid the development process. The API of the sandbox is identical to that of the live Fulfillment API. However, it does not carry out your Member Requests in the carrier's system. 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.noyoconnect.com/auth/public/token. Just follow the instructions above!
After you have generated your access token you can access the sandbox API by hitting:
https://fulfillment-sandbox.noyoconnect.com
Pagination
Code Sample
curl -X GET
--header "Content-Type: application/json"
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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. |
Integration Guide
Integration Philosophy
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 |
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
Mapping plans requires two levels of queries against the API. The first is to get a list of the Group Enrollments by querying the Get Group Enrollments endpoint. A Group Enrollment represents the unique relationship between a Group, Carrier and Line of Coverage (e.g. medical, dental, vision, etc.) Underneath each Group Enrollment there are one more more unique plans, which can be queried using the Group Enrollment Plans endpoint. A common hierarchy 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.
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
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.noyoconnect.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9
Example Response
{
"id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"version": "6b72d72d-cc99-4df6-8152-7183e824c80c",
"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 |
The Group Object
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.noyoconnect.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",
"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 List
meta* |
object |
|
response* |
array |
|
Group Carrier Configurations
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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. |
group_id* |
uuid | Unique identifier of the group in Noyo |
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
configuration* |
object | Carrier configuration details for the group |
List Contacts
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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",
"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 |
meta* |
object |
|
response* |
array |
|
Get Single Contact
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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 |
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 |
List Locations
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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 |
meta* |
object |
|
response* |
array |
|
Get Single Location
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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 |
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 |
|
Employee
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.
Get Single Employee
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4
Example Response
{
"id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
"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": "",
"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"
}
}
}
Returns the latest version of a single employee based on the ID provided.
Path Parameters
employee_id |
The unique identifier of the employee you would like to view |
The Employee Object
id* |
uuid | Unique identifier of the employee in Noyo |
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 |
|
Get Employees in a Group
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
"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": "",
"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"
}
}
}
]
}
Returns a list of all employees for a given group.
Path Parameters
group_id |
The unique identifier of the group for which you would like to view employees |
Get All Employees
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/employees
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
"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": "single",
"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"
}
}
}
]
}
If there is a use case where you need to query employees across all the groups in your organization you can do so using this endpoint. Returns a list of all employees under your organization, regardless of group.
Employee List
meta* |
object |
|
response* |
array |
|
Filtering Employees in a Group
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/employees?first_name=Ann&last_name=Green
There may be some cases where you wish to find a specific employee in a group, but do not know their Noyo id. We provide a way to filter your employee list for a given group via query parameters. The following parameters are accepted by the API in the query string:
first_name |
string | First name of the employee to be filtered on |
last_name |
string | Last name of the employee to be filtered on |
date_of_birth |
date | ISO-8601 date string for the date of birth of the employee to be filtered on |
The filtering is not case-sensitive and it does not require an exact match on the value (e.g. searching for "ann" will match against "Ann" as well as "Annie")
Filtering All Employees
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/employees?first_name=Ann&last_name=Green
There may be some cases where you wish to find a specific employee across all of your groups, but do not know their Noyo id. We provide a way to filter your employee list via query parameters. The following parameters are accepted by the API in the query string:
first_name |
string | First name of the employee to be filtered on |
last_name |
string | Last name of the employee to be filtered on |
date_of_birth |
date | ISO-8601 date string for the date of birth of the employee to be filtered on |
The filtering is not case-sensitive and it does not require an exact match on the value (e.g. searching for "ann" will match against "Ann" as well as "Annie")
Create Employee
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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"
}
}
}
Example Response
{
"id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
"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"
}
}
}
Create a new employee for a group.
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 |
|
Dependent
This object represents an employee's dependent. It contains personal information about the dependent including name, address, contact info, etc. along with the dependent's relationship to the employee.
Get Single Dependent
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/dependents/fd62665c-0846-4e9d-bd29-80779b5f685c
Example Response
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"version": "669fbe16-9960-4069-91aa-832ada3f4e42",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"relationship": "spouse",
"person": {
"first_name": "Diane",
"last_name": "Johnson",
"home_address": {
"street_one": "1234 Home Ave",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
},
"date_of_birth": "1982-01-02",
"ssn": "987654321",
"sex": "F",
"marital_status": "married",
"contact": {
"home_phone": "+12065551234",
"email_address": "diane@testemail.com",
"email_address_type": "home"
}
}
}
Returns the latest version of a single dependent based on the ID provided.
Path Parameters
dependent_id |
The unique identifier of the dependent you would like to view |
The Dependent Object
id* |
uuid | Unique identifier of the dependent in Noyo |
version* |
uuid | Version of the dependent record |
created* |
timestamp | The date the record was originated |
modified* |
timestamp | The date the record was last updated |
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 |
|
Get Dependents
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/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": {
"first_name": "Diane",
"last_name": "Johnson",
"home_address": {
"street_one": "1234 Home Ave",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
},
"date_of_birth": "1982-01-02",
"ssn": "987654321",
"sex": "F",
"marital_status": "",
"contact": {
"home_phone": "+12065551234",
"email_address": "diane@testemail.com",
"email_address_type": "home"
}
}
}
]
}
Returns a list of all dependents for a given employee.
Path Parameters
employee_id |
The unique identifier of the employee for which you would like to view dependents |
Dependent List
meta* |
object |
|
response* |
array |
|
Create Dependent
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/dependents
Body Parameter
{
"relationship": "child",
"person": {
"first_name": "Jamie",
"last_name": "Johnson",
"home_address": {
"street_one": "1234 Home Ave",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
},
"date_of_birth": "2000-01-02",
"ssn": "384032999",
"sex": "F",
"marital_status": "single",
"contact": {
"home_phone": "+12065551234",
"email_address": "jamie@testemail.com",
"email_address_type": "home"
}
}
}
Example Response
{
"id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
"version": "669fbe16-9960-4069-91aa-832ada3f4e42",
"employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"relationship": "child",
"person": {
"first_name": "Jamie",
"last_name": "Johnson",
"home_address": {
"street_one": "1234 Home Ave",
"city": "San Francisco",
"state": "CA",
"zip_code": "94107",
"county": "San Francisco"
},
"date_of_birth": "2000-01-02",
"ssn": "384032999",
"sex": "F",
"marital_status": "single",
"contact": {
"home_phone": "+12065551234",
"email_address": "jamie@testemail.com",
"email_address_type": "home"
}
}
}
Create a new dependent for an employee.
Path Parameters
employee_id |
The unique identifier of the employee the dependent belongs to |
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 |
|
Group Enrollments
This object represents the unique relationship between a Group, Carrier, and line of coverage (e.g. medical, dental, vision)
Get Single Group Enrollment
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/group_enrollments/7499ea07-76c9-40f2-992b-952259e98384
Example Response
{
"id": "7499ea07-76c9-40f2-992b-952259e98384",
"version": "c2292b67-0382-45e9-a378-b52c4129f672",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"line_of_coverage": "medical",
"status": "active",
"open_enrollment_start_date": "2019-01-01",
"open_enrollment_end_date": "2019-02-01",
"effective_start_date": "2019-01-01",
"effective_end_date": "2019-12-31"
}
Returns the latest version of a single group enrollment based on the ID provided.
Path Parameters
enrollment_id |
Unique identifier of the group enrollment |
The Group Enrollment Object
id* |
uuid | Unique identifier of the group enrollment in Noyo |
version* |
uuid | Version of the group enrollment record |
group_id* |
uuid | Unique identifier of the group in Noyo |
carrier_id* |
uuid | Unique identifier of the carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group enrollment. One of: add, dental, life, ltd, medical, std, vision |
status* |
string | Status of the group enrollment. One of: active, completed, pending |
open_enrollment_start_date |
date | ISO-8601 date string for the open enrollment start date of the group enrollment |
open_enrollment_end_date |
date | ISO-8601 date string for the open enrollment end date of the group enrollment |
effective_start_date |
date | ISO-8601 date string for the effective start date of the group enrollment |
effective_end_date |
date | ISO-8601 date string for the effective end date of the group enrollment |
created* |
timestamp | The date the record was originated |
modified* |
timestamp | The date the record was last updated |
Get Group Enrollments
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/group_enrollments
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"id": "7499ea07-76c9-40f2-992b-952259e98384",
"version": "c2292b67-0382-45e9-a378-b52c4129f672",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"line_of_coverage": "medical",
"status": "active",
"open_enrollment_start_date": "2019-01-01",
"open_enrollment_end_date": "2019-02-01",
"effective_start_date": "2019-01-01",
"effective_end_date": "2019-12-31"
},
{
"id": "25cdcb18-7d01-4599-9f65-d38b36d7c370",
"version": "55c4bcbb-98ab-448d-a5b4-d7d835327f72",
"group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
"carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
"line_of_coverage": "dental",
"status": "active",
"open_enrollment_start_date": "2019-01-01",
"open_enrollment_end_date": "2019-02-01",
"effective_start_date": "2019-01-01",
"effective_end_date": "2019-12-31"
}
]
}
Returns a list of all group enrollments for a given group.
Path Parameters
group_id |
The unique identifier of the group for which you would like to view group enrollments |
Group Enrollment List
meta* |
object |
|
response* |
array |
|
Group Plans
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/groups/31559b4b-e45a-4df8-84f6-2220d7ed0c3a/plans
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 2
},
"response": [
{
"cobra_rules": {
"eligible": false
},
"code": "D1",
"created": 1554175253,
"eligible_member_types": [
"employee"
],
"group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
"id": "5ba915fc-afe8-4572-a60f-61ee5883e100",
"line_of_coverage": "dental",
"modified": 1554175253,
"name": "Dental - Employee",
"network": "Dental PPO Network",
"plan_type": "ppo",
"termination_policy": "end_of_month",
"version": "1bf06a82-8d81-4849-91d3-47c60fdce605",
"voluntary": false,
"waiting_periods": [
{
"waiting_period_enrollment_type": "new_member",
"waiting_period_rule": "hire_date"
},
{
"waiting_period_amount": 0,
"waiting_period_enrollment_type": "current_member",
"waiting_period_rule": "after_waiting_period",
"waiting_period_unit": "day"
}
]
},
{
"cobra_rules": {
"eligible": false
},
"code": "D1",
"created": 1554175253,
"eligible_member_types": [
"spouse",
"child"
],
"group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
"id": "c1279c1c-ed61-439b-bd9c-07f3228c09cb",
"line_of_coverage": "dental",
"modified": 1554175253,
"name": "Dental - Dependent",
"network": "Dental PPO Network",
"plan_type": "ppo",
"termination_policy": "end_of_month",
"version": "a6404fb2-f266-45b0-a6b7-84b047f017cf",
"voluntary": false,
"waiting_periods": [
{
"waiting_period_enrollment_type": "new_member",
"waiting_period_rule": "hire_date"
},
{
"waiting_period_amount": 0,
"waiting_period_enrollment_type": "current_member",
"waiting_period_rule": "after_waiting_period",
"waiting_period_unit": "day"
}
]
}
]
}
Returns a list of all plans for a given group.
Path Parameters
group_id |
The unique identifier of the group for which you would like to view plans |
Group Enrollment Plans
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/group_enrollments/31559b4b-e45a-4df8-84f6-2220d7ed0c3a/plans
Example Response
[
{
"id": "5ba915fc-afe8-4572-a60f-61ee5883e100",
"version": "1bf06a82-8d81-4849-91d3-47c60fdce605",
"group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
"name": "Dental",
"code": "D1",
"plan_type": "ppo",
"network": "Dental PPO Network",
"voluntary": false,
"eligible_member_types": [
"employee"
],
"cobra_rules": {
"eligible": false
},
"created": 1554175253,
"modified": 1554175253
},
{
"id": "c1279c1c-ed61-439b-bd9c-07f3228c09cb",
"version": "a6404fb2-f266-45b0-a6b7-84b047f017cf",
"group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
"name": "Dental",
"code": "D1",
"plan_type": "ppo",
"network": "Dental PPO Network",
"voluntary": false,
"eligible_member_types": [
"spouse",
"child"
],
"cobra_rules": {
"eligible": false
},
"created": 1554175253,
"modified": 1554175253
}
]
Returns a list of all plans for a given group enrollment.
Path Parameters
enrollment_id |
The unique identifier of the group enrollment for which you would like to view the plans |
AD&D Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group AD&D plan |
name* |
string | Name of the group AD&D plan |
code |
string | Plan code of the group AD&D plan |
plan_type* |
string | Type of group AD&D plan. One of: basic, voluntary |
status* |
string | Status of the group AD&D plan. One of: active, discontinued, pending |
eligible_member_types* |
array | List of member types eligible for the group AD&D plan. One of: all, child, domestic-partner, employee, spouse |
waiting_periods* |
array | Member waiting period details for the group AD&D plan |
termination_policy* |
string | Termination policy for the group AD&D plan. One of: end_of_month, last_work_date |
volume_rules* |
object | Volume rules for the group AD&D plan |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Dental Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group dental plan |
name* |
string | Name of the group dental plan |
code |
string | Plan code of the group dental plan |
plan_type |
string | Type of group dental plan |
network |
string | Network name of the plan designated by the carrier |
voluntary |
boolean | True if the group dental plan is a voluntary plan |
status* |
string | Status of the group dental plan. One of: active, discontinued, pending |
eligible_member_types* |
array | List of member types eligible for the group dental plan. One of: all, child, domestic-partner, employee, spouse |
waiting_periods* |
array | Member waiting period details for the group dental plan |
termination_policy* |
string | Termination policy for the group dental plan. One of: end_of_month, last_work_date |
cobra_rules* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Life Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group life plan |
name* |
string | Name of the group life plan |
code |
string | Plan code of the group life plan |
plan_type* |
string | Type of group life plan. One of: basic, voluntary |
status* |
string | Status of the group life plan. One of: active, discontinued, pending |
eligible_member_types* |
array | List of member types eligible for the group life plan. One of: all, child, domestic-partner, employee, spouse |
waiting_periods* |
array | Member waiting period details for the group life plan |
termination_policy* |
string | Termination policy for the group life plan. One of: end_of_month, last_work_date |
volume_rules* |
object | Volume rules for the group life plan |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
LTD Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group LTD plan |
name* |
string | Name of the group LTD plan |
code |
string | Plan code of the group LTD plan |
plan_type* |
string | Type of group LTD plan. One of: basic, voluntary |
status* |
string | Status of the group LTD plan. One of: active, discontinued, pending |
eligible_member_types* |
array | List of member types eligible for the group LTD plan. One of: all, child, domestic-partner, employee, spouse |
waiting_periods* |
array | Member waiting period details for the group LTD plan |
termination_policy* |
string | Termination policy for the group LTD plan. One of: end_of_month, last_work_date |
volume_rules* |
object | Volume rules for the group LTD plan |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Medical Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group medical plan |
name* |
string | Name of the group medical plan |
code |
string | Plan code of the group medical plan |
plan_type |
string | Type of group medical plan |
network |
string | Network name of the plan designated by the carrier |
metal_tier |
string | Metal tier designation of the group medical plan |
status* |
string | Status of the group medical plan. One of: active, discontinued, pending |
waiting_periods* |
array | Member waiting period details for the group medical plan |
termination_policy* |
string | Termination policy for the group medical plan. One of: end_of_month, last_work_date |
cobra_rules* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
STD Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group STD plan |
name* |
string | Name of the group STD plan |
code |
string | Plan code of the group STD plan |
plan_type* |
string | Type of group STD plan. One of: basic, voluntary |
status* |
string | Status of the group STD plan. One of: active, discontinued, pending |
eligible_member_types* |
array | List of member types eligible for the group STD plan. One of: all, child, domestic-partner, employee, spouse |
waiting_periods* |
array | Member waiting period details for the group STD plan |
termination_policy* |
string | Termination policy for the group STD plan. One of: end_of_month, last_work_date |
volume_rules* |
object | Volume rules for the group STD plan |
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Vision Plan Object
id* |
uuid | Unique identifier of the record in Noyo |
version* |
uuid | Current version of the record |
group_enrollment_id* |
uuid | Unique identifier of the associated group enrollment in the Noyo system |
carrier_id* |
uuid | Unique identifier of the associated carrier in Noyo |
line_of_coverage* |
string | Line of coverage for the group vision plan |
name* |
string | Name of the group vision plan |
code |
string | Plan code of the group vision plan |
voluntary |
boolean | True if the group vision plan is a voluntary plan |
status* |
string | Status of the group vision plan. One of: active, discontinued, pending |
eligible_member_types* |
array | List of member types eligible for the group vision plan. One of: all, child, domestic-partner, employee, spouse |
waiting_periods* |
array | Member waiting period details for the group vision plan |
termination_policy* |
string | Termination policy for the group vision plan. One of: end_of_month, last_work_date |
cobra_rules* |
object |
|
created* |
timestamp | The date the record was created |
modified* |
timestamp | The date the record was last updated |
Individual Enrollments
This object represents an individual's (employee or dependent) relationship with enrolling or waiving a line of coverage with a carrier. These are the end-product of member requests submitted through this API. They are not directly created from end-user API actions.
Single Individual Enrollment
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/individual_enrollments/6670f290-4236-4690-bece-a110f9ad924b
Example Response
{
"id": "6670f290-4236-4690-bece-a110f9ad924b",
"version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
"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": {
"premium": {
"amount": 50,
"unit": "Month"
}
},
"effective_start_date": "2018-10-01",
"effective_end_date": "2019-10-01",
"individual_enrollment_configuration": {},
"created": 1557512389,
"modified": 1564440756
}
Returns the latest version of a single individual enrollment based on the ID provided.
Path Parameters
individual_enrollment_id |
Unique identifier of the individual enrollment |
By Employee
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/individual_enrollments
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "6670f290-4236-4690-bece-a110f9ad924b",
"version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
"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": {
"premium": {
"amount": 50,
"unit": "Month"
}
},
"effective_start_date": "2018-10-01",
"effective_end_date": "2019-10-01",
"individual_enrollment_configuration": {},
"created": 1557512389,
"modified": 1564440756
}
]
}
Returns a list of all individual enrollments for a given employee.
Path Parameters
employee_id |
The unique identifier of the employee for which you would like to view individual enrollments |
By Dependent
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.com/api/v1/dependents/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/individual_enrollments
Example Response
{
"meta": {
"offset": 0,
"page_num": 1,
"page_size": 20,
"total_records": 1
},
"response": [
{
"id": "6670f290-4236-4690-bece-a110f9ad924b",
"version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
"group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
"line_of_coverage": "medical",
"status": "active",
"individual_type": "dependent",
"individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
"plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
"enroll_data": {
"premium": {
"amount": 50,
"unit": "Month"
}
},
"effective_start_date": "2018-10-01",
"effective_end_date": "2019-10-01",
"individual_enrollment_configuration": {},
"created": 1557512389,
"modified": 1564440756
}
]
}
Returns a list of all individual enrollments for a given dependent.
Path Parameters
dependent_id |
The unique identifier of the employee for which you would like to view individual enrollments |
Individual Enrollment List
meta* |
object |
|
response* |
array |
|
Creating Member Requests
Member Requests and Member Transactions are the heart and soul of the Noyo Fulfillment API. They represent the core operations you want to carry out on behalf of members (employees & dependents) at one or many carrier partners. The following member requests are supported by the Noyo platform:
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 maybe 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 the contents were incorrect or you wanted it cancelled completely while processing. |
As far as state transitions, expect the progression to be linear, from processing to either completed or failed. Once in completed or failed, 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.
New Hire Enrollment
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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 |
|---|---|
add |
Accidental Death & Dismemberment |
dental |
Dental |
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 or group enrollment plans endpoint.
Enrolling in medical, dental, vision
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 |
Enrolling in life, add, std and ltd
Life, AD&D, STD and LTD 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.noyoconnect.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
Termination
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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.noyoconnect.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",
"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 |
None |
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.
Qualifying Life Event
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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, court_order, death, dependent_open_enrollment, divorce, foster_care, immigration_status_change, legal_guardian, lost_coverage, marriage, medicare, moved, newborn, rate_changed, rehire |
event_date* |
string | ISO-8601 date string for qualifying life event date |
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 |
|---|---|
add |
Accidental Death & Dismemberment |
dental |
Dental |
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 or group enrollment 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 |
|
Adding life, add, std and ltd coverage
Life, AD&D, STD and LTD 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 / line of coverage combination, given that the member already has coverage with a carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's life or disability plan, or change the member's coverage by selecting a different available medical plan.
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 |
Adding life, add, std and ltd coverage
Life, AD&D, STD and LTD 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
A qualifying life event transaction is created for each action type for each entry in the coverages array (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.
Open Enrollment
Code Sample
curl -X POST
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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": "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"
}
]
}
}
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 |
|---|---|
add |
Accidental Death & Dismemberment |
dental |
Dental |
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 enrollment.
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 |
|
Adding life, add, std and ltd coverage
Life, AD&D, STD and LTD 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 / line of coverage combination, given that the member already has coverage with a carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's life or disability plan, or change the member's coverage by selecting a different available medical plan.
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 |
Adding life, add, std and ltd coverage
Life, AD&D, STD and LTD 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
A open enrollment transaction is created for each action type for each entry in the coverages array (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.
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.noyoconnect.com/api/v1/member_requests/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1
Example Response
{
"id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
"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 |
The Member Request Object
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 |
employee_id* |
uuid | Unique identifier of the employee in Noyo |
request_type* |
string | Transaction type for the member request. One of: demographic, new_hire, open_enrollment, qualifying_life_event, termination |
status* |
string | Status of the member request. One of: 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.noyoconnect.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",
"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",
"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 |
Get All Member Requests
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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",
"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.
Member Request List
meta* |
object |
|
response* |
array |
|
Filtering Member Requests
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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: completed, failed, processing |
request_type |
string | Member request type to be filtered on. One of: demographic, 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.noyoconnect.com/api/v1/member_transactions/a6e30204-87b2-4802-95a4-a156bd0f7435
Example Response
{
"id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
"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 |
The Member Transaction Object
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: add, dental, life, ltd, medical, std, vision |
transaction_type* |
string | Transaction type of the member transaction. One of: carrier_demographic, 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: 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.noyoconnect.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",
"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 |
Get All Member Transactions
Code Sample
curl -X GET
--header "Authorization: Bearer <ACCESS_TOKEN>"
https://fulfillment.noyoconnect.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",
"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
Member Transaction List
meta* |
object |
|
response* |
array |
|