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:

• New Hire Enrollment
• Termination
• Demographic Change
• Qualifying Life Event
• Open Enrollment

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	offset: Value passed in via the query parameters page_num: Current page number, computed using total_records and page_size page_size: Value passed in via the query parameters total_records: Total number of records available in the API
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:

• New Hire Enrollment
• Termination
• Demographic Change
• Qualifying Life Event
• Open Enrollment

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 group in Noyo
version*	uuid	Version of the group record
created*	timestamp	The date the record was originated
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.

Group List

meta*	object	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifier of the group in Noyo version*: Version of the group record created*: The date the record was originated modified*: The date the record was last updated organization_id*: Unique identifier of the platform or broker organization in Noyo name*: Name of the group sic_code: SIC Code of the group dba_name: DBA name for the company, if applicable federal_ein: Federal Employer Identification Number for the company

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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifier of the group contact in Noyo version*: Version of the group contact record created*: The date the record was originated modified*: The date the record was last updated group_id*: Unique identifier of the group in Noyo first_name: First name of the group contact last_name: Last name of the group contact title: Job title of the group contact email: Work email address of the group contact phone_number: Work phone number of the group contact in E.164 format types*: List of contact types for the group contact. One or more of: billing, company, executive, online primary_contact: True if contact is the primary contact for the group

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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifer of the group location in Noyo version*: Version of the group location record created*: The date the record was originated modified*: The date the record was last updated group_id*: Unique identifier of the group in Noyo display_name*: Display name for the group location address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address

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 identifer of the group location in Noyo
version*	uuid	Version of the group location 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
display_name*	string	Display name for the group location
address*	object	street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address

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	first_name*: First name of the person middle_name: Middle name of the person last_name*: Last name of the person suffix: Suffix of the person home_address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address mailing_address: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address date_of_birth*: ISO-8601 date string for the date of birth of the person ssn: Social Security Number of the person sex*: Sex of the person. One of: F, M, U marital_status: Marital status of the person (deprecated) maiden_name: Maiden name of the person (deprecated) contact: home_phone: Home phone number in E.164 format work_phone: Work phone number in E.164 format email_address: Email address of the person email_address_type: Type of email address preferred_method: Preferred method of contact for the person. One of: email, home-phone, mail, other, work-phone preferred_language: Preferred written or spoken language of the person speaks_english: True if the person can speak or communicate in English details: tobacco: user: True if the person uses tobacco of any kind types: List of types of tobacco use. One or more of: chewing-tobacco, cigarettes, pipe duration: Duration of tobacco use frequency: Frequency of tobacco use disability: reason: Description of the disability communication: True if the disability impacts the ability to communicate or read american_indian: state: Primary state of the federally-recognized American Indian or Alaska Native tribe, if applicable. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY tribe: Name of the federally-recognized American Indian or Alaska Native tribe, if applicable is_student: True if the person is a student is_military: True if the person is in the military
employment*	object	employment_status*: Employee employment status. One of: contract, disabled, full-time, part-time, retired, terminated occupation: Employee occupation or job title hours_worked*: An integer of hours worked per week by the employee salary: amount*: Amount of salary earned by the employee in US dollars and cents, as a decimal value unit*: Unit of salary earned by the employee. One of: annual, hour, month, semi-monthly, week type*: Type of salary earned by the employee. One of: hourly, salary employment_dates*: hire_date*: ISO-8601 date string for the hire date of the employee full_time_start: ISO-8601 date string for start date as a full time employee with the group (if applicable) terminated: ISO-8601 date string for the termination date of the employee (if applicable) rehire: ISO-8601 date string for the rehire date of the employee (if applicable) retirement: ISO-8601 date string for the retirement date of the employee (if applicable)

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": "",
                "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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifier of the employee in Noyo version*: Version of the employee record created*: The date the record was originated modified*: The date the record was last updated group_id*: Unique identifier of the group in Noyo location_id: Unique identifier of the employee group location in Noyo person*: first_name*: First name of the person middle_name: Middle name of the person last_name*: Last name of the person suffix: Suffix of the person home_address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address mailing_address: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address date_of_birth*: ISO-8601 date string for the date of birth of the person ssn: Social Security Number of the person sex*: Sex of the person. One of: F, M, U marital_status: Marital status of the person (deprecated) maiden_name: Maiden name of the person (deprecated) contact: home_phone: Home phone number in E.164 format work_phone: Work phone number in E.164 format email_address: Email address of the person email_address_type: Type of email address preferred_method: Preferred method of contact for the person. One of: email, home-phone, mail, other, work-phone preferred_language: Preferred written or spoken language of the person speaks_english: True if the person can speak or communicate in English details: tobacco: user: True if the person uses tobacco of any kind types: List of types of tobacco use. One or more of: chewing-tobacco, cigarettes, pipe duration: Duration of tobacco use frequency: Frequency of tobacco use disability: reason: Description of the disability communication: True if the disability impacts the ability to communicate or read american_indian: state: Primary state of the federally-recognized American Indian or Alaska Native tribe, if applicable. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY tribe: Name of the federally-recognized American Indian or Alaska Native tribe, if applicable is_student: True if the person is a student is_military: True if the person is in the military employment*: employment_status*: Employee employment status. One of: contract, disabled, full-time, part-time, retired, terminated occupation: Employee occupation or job title hours_worked*: An integer of hours worked per week by the employee salary: amount*: Amount of salary earned by the employee in US dollars and cents, as a decimal value unit*: Unit of salary earned by the employee. One of: annual, hour, month, semi-monthly, week type*: Type of salary earned by the employee. One of: hourly, salary employment_dates*: hire_date*: ISO-8601 date string for the hire date of the employee full_time_start: ISO-8601 date string for start date as a full time employee with the group (if applicable) terminated: ISO-8601 date string for the termination date of the employee (if applicable) rehire: ISO-8601 date string for the rehire date of the employee (if applicable) retirement: ISO-8601 date string for the retirement date of the employee (if applicable)

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": "",
        "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": "",
        "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	first_name*: First name of the person middle_name: Middle name of the person last_name*: Last name of the person suffix: Suffix of the person home_address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address mailing_address: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address date_of_birth*: ISO-8601 date string for the date of birth of the person ssn: Social Security Number of the person sex*: Sex of the person. One of: F, M marital_status: Marital status of the person (deprecated) maiden_name: Maiden name of the person (deprecated) contact: home_phone: Home phone number in E.164 format work_phone: Work phone number in E.164 format email_address: Email address of the person email_address_type: Type of email address preferred_method: Preferred method of contact for the person. One of: email, home-phone, mail, other, work-phone preferred_language: Preferred written or spoken language of the person speaks_english: True if the person can speak or communicate in English details: tobacco: user: True if the person uses tobacco of any kind types: List of types of tobacco use. One or more of: chewing-tobacco, cigarettes, pipe duration: Duration of tobacco use frequency: Frequency of tobacco use disability: reason: Description of the disability communication: True if the disability impacts the ability to communicate or read american_indian: state: Primary state of the federally-recognized American Indian or Alaska Native tribe, if applicable. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY tribe: Name of the federally-recognized American Indian or Alaska Native tribe, if applicable is_student: True if the person is a student is_military: True if the person is in the military
employment*	object	employment_status*: Employee employment status. One of: contract, disabled, full-time, part-time, retired, terminated occupation: Employee occupation or job title hours_worked*: An integer of hours worked per week by the employee salary: amount*: Amount of salary earned by the employee in US dollars and cents, as a decimal value unit*: Unit of salary earned by the employee. One of: annual, hour, month, semi-monthly, week type*: Type of salary earned by the employee. One of: hourly, salary employment_dates*: hire_date*: ISO-8601 date string for the hire date of the employee full_time_start: ISO-8601 date string for start date as a full time employee with the group (if applicable) terminated: ISO-8601 date string for the termination date of the employee (if applicable) rehire: ISO-8601 date string for the rehire date of the employee (if applicable) retirement: ISO-8601 date string for the retirement date of the employee (if applicable)

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": "",
        "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, legal-guardianship, other, spouse, step-child
person*	object	first_name*: First name of the person middle_name: Middle name of the person last_name*: Last name of the person suffix: Suffix of the person home_address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address mailing_address: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address date_of_birth*: ISO-8601 date string for the date of birth of the person ssn: Social Security Number of the person sex*: Sex of the person. One of: F, M, U marital_status: Marital status of the person (deprecated) maiden_name: Maiden name of the person (deprecated) contact: home_phone: Home phone number in E.164 format work_phone: Work phone number in E.164 format email_address: Email address of the person email_address_type: Type of email address preferred_method: Preferred method of contact for the person. One of: email, home-phone, mail, other, work-phone preferred_language: Preferred written or spoken language of the person speaks_english: True if the person can speak or communicate in English details: tobacco: user: True if the person uses tobacco of any kind types: List of types of tobacco use. One or more of: chewing-tobacco, cigarettes, pipe duration: Duration of tobacco use frequency: Frequency of tobacco use disability: reason: Description of the disability communication: True if the disability impacts the ability to communicate or read american_indian: state: Primary state of the federally-recognized American Indian or Alaska Native tribe, if applicable. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY tribe: Name of the federally-recognized American Indian or Alaska Native tribe, if applicable is_student: True if the person is a student is_military: True if the person is in the military

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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifier of the dependent in Noyo version*: Version of the dependent record created*: The date the record was originated modified*: The date the record was last updated employee_id*: Unique identifier of the employee in Noyo relationship*: Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, legal-guardianship, other, spouse, step-child person*: first_name*: First name of the person middle_name: Middle name of the person last_name*: Last name of the person suffix: Suffix of the person home_address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address mailing_address: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address date_of_birth*: ISO-8601 date string for the date of birth of the person ssn: Social Security Number of the person sex*: Sex of the person. One of: F, M, U marital_status: Marital status of the person (deprecated) maiden_name: Maiden name of the person (deprecated) contact: home_phone: Home phone number in E.164 format work_phone: Work phone number in E.164 format email_address: Email address of the person email_address_type: Type of email address preferred_method: Preferred method of contact for the person. One of: email, home-phone, mail, other, work-phone preferred_language: Preferred written or spoken language of the person speaks_english: True if the person can speak or communicate in English details: tobacco: user: True if the person uses tobacco of any kind types: List of types of tobacco use. One or more of: chewing-tobacco, cigarettes, pipe duration: Duration of tobacco use frequency: Frequency of tobacco use disability: reason: Description of the disability communication: True if the disability impacts the ability to communicate or read american_indian: state: Primary state of the federally-recognized American Indian or Alaska Native tribe, if applicable. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY tribe: Name of the federally-recognized American Indian or Alaska Native tribe, if applicable is_student: True if the person is a student is_military: True if the person is in the military

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": "",
        "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": "",
        "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, legal-guardianship, other, spouse, step-child
person*	object	first_name*: First name of the person middle_name: Middle name of the person last_name*: Last name of the person suffix: Suffix of the person home_address*: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address mailing_address: street_one*: Line one of the address street_two: Line two of the address city*: City of the address state*: State postal code of the address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the address county: County of the address date_of_birth*: ISO-8601 date string for the date of birth of the person ssn: Social Security Number of the person sex*: Sex of the person. One of: F, M marital_status: Marital status of the person (deprecated) maiden_name: Maiden name of the person (deprecated) contact: home_phone: Home phone number in E.164 format work_phone: Work phone number in E.164 format email_address: Email address of the person email_address_type: Type of email address preferred_method: Preferred method of contact for the person. One of: email, home-phone, mail, other, work-phone preferred_language: Preferred written or spoken language of the person speaks_english: True if the person can speak or communicate in English details: tobacco: user: True if the person uses tobacco of any kind types: List of types of tobacco use. One or more of: chewing-tobacco, cigarettes, pipe duration: Duration of tobacco use frequency: Frequency of tobacco use disability: reason: Description of the disability communication: True if the disability impacts the ability to communicate or read american_indian: state: Primary state of the federally-recognized American Indian or Alaska Native tribe, if applicable. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY tribe: Name of the federally-recognized American Indian or Alaska Native tribe, if applicable is_student: True if the person is a student is_military: True if the person is in the military

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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifier of the group enrollment in Noyo version*: Version of the group enrollment record group_id*: Unique identifier of the group in Noyo carrier_id*: Unique identifier of the carrier in Noyo line_of_coverage*: Line of coverage for the group enrollment. One of: add, dental, life, ltd, medical, std, vision status*: Status of the group enrollment. One of: active, completed, pending open_enrollment_start_date: ISO-8601 date string for the open enrollment start date of the group enrollment open_enrollment_end_date: ISO-8601 date string for the open enrollment end date of the group enrollment effective_start_date: ISO-8601 date string for the effective start date of the group enrollment effective_end_date: ISO-8601 date string for the effective end date of the group enrollment created*: The date the record was originated modified*: The date the record was last updated

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 group AD&D plan in Noyo
version*	uuid	Version of the group AD&D plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group AD&D plan
code	string	Plan code or product code assigned by the carrier
plan_type*	string	Type of group AD&D plan
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
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated

Dental Plan Object

id*	uuid	Unique identifier of the group dental plan in Noyo
version*	uuid	Version of the group dental plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group dental plan
code	string	Plan code or product code assigned by the carrier
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
cobra_rules*	object	eligible: True if group plan is eligible for COBRA enrollments
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated

Life Plan Object

id*	uuid	Unique identifier of the group life plan in Noyo
version*	uuid	Version of the group life plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group life plan
code	string	Plan code or product code assigned by the carrier
plan_type*	string	Type of group life plan
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
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated

LTD Plan Object

id*	uuid	Unique identifier of the group LTD plan in Noyo
version*	uuid	Version of the group LTD plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group LTD plan
code	string	Plan code or product code assigned by the carrier
plan_type*	string	Type of group LTD plan
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
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated

Medical Plan Object

id*	uuid	Unique identifier of the group medical plan in Noyo
version*	uuid	Version of the group medical plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group medical plan
code	string	Plan code or product code assigned by the carrier
plan_type*	string	Type of group medical plan
network*	string	Network name of the plan designated by the carrier
metal_tier*	string	Metal tier of plan of the group medical plan
status*	string	Status of the group medical plan. One of: active, discontinued, pending
cobra_rules*	object	eligible: True if group plan is eligible for COBRA enrollments
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated

STD Plan Object

id*	uuid	Unique identifier of the group STD plan in Noyo
version*	uuid	Version of the group STD plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group STD plan
code	string	Plan code or product code assigned by the carrier
plan_type*	string	Type of group STD plan
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
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated

Vision Plan Object

id*	uuid	Unique identifier of the group vision plan in Noyo
version*	uuid	Version of the group vision plan record
group_enrollment_id*	uuid	Unique identifier of the group enrollment in Noyo
name*	string	Name of the group vision plan
code	string	Plan code or product code assigned by the carrier
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
cobra_rules*	object	eligible: True if group plan is eligible for COBRA enrollments
created*	timestamp	The date the record was originated
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.

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"
                }
            }
        }
    ]
}

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"
                }
            }
        }
    ]
}

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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifier of the individual enrollment in Noyo version*: Version of the individual enrollment record group_enrollment_id*: Unique identifier of the group enrollment in Noyo line_of_coverage*: Line of coverage for the individual enrollment. One of: add, dental, life, ltd, medical, std, vision status*: Status of the individual enrollment. One of: active, pending, terminated, waived individual_type*: Type of member for the individual enrollment. One of: dependent, employee individual_id*: Unique identifier of the employee or dependent in Noyo plan_id*: Unique identifier of the group plan in Noyo enroll_data*: Line of coverage specific enroll data about premiums and volumes effective_start_date: ISO-8601 date string for the effective date of the coverage effective_end_date: ISO-8601 date string for the effective date of the coverage created*: The date the record was originated modified*: The date the record was last updated

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:

• New Hire Enrollment
• Termination
• Demographic Change
• Qualifying Life Event
• Open Enrollment

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.

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 employing 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 along with the plan_id and in some cases additional information. The plan_id can be retrieved by selecting a valid plan from the group enrollment.

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	member*: id*: Unique identifier of the employee or dependent in Noyo type*: Type of member making a demographic request. One of: dependent, employee name_change: first_name*: New first name of the person middle_name: New middle name of the person last_name*: New last name of the person suffix: New name suffix of the person address_change: home_address: street_one*: Line one of the new address street_two: Line two of the new address city*: City of the new address state*: State postal code of the new address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the new address county: County of the new address mailing_address: street_one*: Line one of the new address street_two: Line two of the new address city*: City of the new address state*: State postal code of the new address. One of: AK, AL, AR, AS, AZ, CA, CO, CT, DC, DE, FL, FM, GA, GU, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MH, MI, MN, MO, MP, MS, MT, NC, ND, NE, NH, NJ, NM, NV, NY, OH, OK, OR, PA, PR, PW, RI, SC, SD, TN, TX, UM, UT, VA, VI, VT, WA, WI, WV, WY zip_code*: Zip code of the new address county: County of the new address contact_change: home_phone: New home phone number in E.164 format work_phone: New work phone number in E.164 format email_address: New email address of the person email_address_type: Type of new email address. One of: home, work ssn_change: ssn*: New or corrected Social Security Number of the person dob_change: date_of_birth*: ISO-8601 date string for the new or corrected date of birth of the person sex_change: sex*: New sex of the person. One of: F, M employment_change: hire_date: ISO-8601 date string for the new or corrected hire date of the employee employment_status: New or updated employee employment status. One of: contract, disabled, full-time, part-time, retired, terminated occupation: New or updated employee occupation or job title hours_worked: New number of hours worked per week by the employee salary_change: amount*: New or updated amount of salary earned by the employee in US dollars unit*: New or updated unit of salary earned by the employee. One of: annual, hour, month, semi-monthly, week type*: New or updated type of salary earned by the employee. One of: hourly, salary

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 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	carrier_name*: Name of insurance carrier providing prior coverage last_coverage_date*: ISO-8601 date string of the last day of coverage with the prior insurance carrier

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	carrier_name*: Name of insurance carrier providing prior coverage last_coverage_date*: ISO-8601 date string of the last day of coverage with the prior insurance carrier

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	carrier_name*: Name of insurance carrier providing prior coverage last_coverage_date*: ISO-8601 date string of the last day of coverage with the prior insurance carrier

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	carrier_name*: Name of insurance carrier providing prior coverage last_coverage_date*: ISO-8601 date string of the last day of coverage with the prior insurance carrier

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 identifer of the group location in Noyo
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
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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifer of the group location in Noyo created*: The date the record was originated modified*: The date the record was last updated employee_id*: Unique identifier of the employee in Noyo request_type*: Transaction type for the member request. One of: demographic, new_hire, open_enrollment, qualifying_life_event, termination status*: Status of the member request. One of: completed, failed, processing transactions: List of unique identifiers of all associated member transactions in Noyo body*: Data required to execute a member request, varies depending on the request type result*: Result from executing the member request, varies depending on the request type

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 identifer of the member transaction in Noyo
created*	timestamp	The date the record was originated
modified*	timestamp	The date the record was last updated
member_request_id*	uuid	Unique identifer of the member request in Noyo
employee_id*	uuid	Unique identifer of the employee in Noyo
carrier_id	uuid	Unique identifer of the carrier in Noyo
lines_of_coverage	array	List of lines of coverage in the member transaction
transaction_type*	string	Type of the member transaction
status*	string	Status of the member transaction
verified	timestamp	The date the member transaction was verified
body*	object	Data required to execute a member transaction, varies depending on transaction type
result*	object	Data describing the result of a completed member transaction, varies depending on transaction type

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	offset*: The offset of the first response record within the matching data set page_num*: The page number of the response records within the overall data set (1-based integer) page_size*: The maximum number of response records on each page of results total_records*: The total number of records in the entire matching data set
response*	array	id*: Unique identifer of the member transaction in Noyo created*: The date the record was originated modified*: The date the record was last updated member_request_id*: Unique identifer of the member request in Noyo employee_id*: Unique identifer of the employee in Noyo carrier_id: Unique identifer of the carrier in Noyo lines_of_coverage: List of lines of coverage in the member transaction transaction_type*: Type of the member transaction status*: Status of the member transaction verified: The date the member transaction was verified body*: Data required to execute a member transaction, varies depending on transaction type result*: Data describing the result of a completed member transaction, varies depending on transaction type