NAV Navbar
cURL

Noyo Group Benefits API

Scroll down for code samples, example requests and responses.

The Noyo group benefits API enables benefits administration platforms to seamlessly manage group benefits policies with many insurance carriers simultaneously. Noyo automates administration across the entire policy lifecycle, from initial group installation through setup, ongoing eligibility management, and renewal.

Get started by connecting a group: Connecting a group is necessary for groups that already exist at the carrier. Once a group is successfully connected, you can begin sending policy management requests through Noyo.

Notes

In the field lists in this document...

* designates that field is required

ˢ designates that field is situationally required

All datetimes can be assumed to be represented in UTC timezone, unless otherwise noted. Datetimes expressed as an integer value are relative to the Unix epoch.

How Noyo’s API is unique

You may notice that many service endpoints do not support methods to directly create or update particular objects (member transactions, individual enrollments, groups, etc.). Instead of this approach, Noyo provides interfaces that allow you to request that actions be taken, such as a member request or a group connection. These requests are routed through Noyo’s enrollment rules and the carrier system, which can in turn create or update read-only objects. This separation between requests and results ensures that requested actions are routed through the appropriate channels and result in the appropriate action; it also allows you to discover the status of a given request.

Authentication

Code Sample

curl -X POST
 --header "Content-Type: application/json"
 --header "Authorization: Basic <Base64Encode(<CLIENT_ID>:<CLIENT_SECRET>)>"
 --data '{"grant_type": "client_credentials"}'
 https://accounts.noyo.com/auth/public/token

Example Response

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": 864000,
  "token_type": "Bearer"
}

Each customer account has a unique pair of API credentials. Contact Noyo support to receive an CLIENT_ID, CLIENT_SECRET pair as part the initial onboarding.

Getting a Token

In order to make API calls to Noyo's API you just generate a temporary access token (valid for 10 minutes) by calling https://accounts.noyo.com/auth/public/token using your CLIENT_ID and CLIENT_SECRET as the username/password combination in a Basic Authentication header.

Calling the API

After generating the token using the instructions above, include the ACCESS_TOKEN in the Authorization header for each request: Authorization: Bearer <ACCESS_TOKEN>.

Sandbox

Noyo provides a sandbox environment for our APIs to aid the development process. The API of the sandbox is identical to that of the live services. However, it does not carry out your actions against insurance carrier systems. This will allow you to develop and test your Noyo integration before going live. You can use your sandbox API credentials to generate an access token from https://accounts.noyo.com/auth/public/token. Just follow the authentication instructions!

After you have generated your access token you can access the sandbox API for each service by using these domains:

Group Installation: https://group-installation-sandbox.noyo.com

Fulfillment: https://fulfillment-sandbox.noyo.com

Member Requests on Sandbox

A member request created on the sandbox API will initially return in the processing status. Within a random period of time after submission, up to 15 seconds, it will return in the completed status. See member request statuses for more information.

Renewal Decisions on Sandbox

A renewal decision created on the sandbox API will initially return in the submitted status. Within a random period of time, up to 15 seconds, it will return with an updated status, based on the scenarios below. This will simulate the process of a renewal decision being compared against carrier data. See renewal decision statuses for more information.

Renewal decision scenarios

Different renewal decision scenarios can be captured on the sandbox by using the renewal date's day of the month as a special value.

By supplying a renewal date with a day of the month of the following values, you will trigger the following scenarios:

Renewal Date - Day of Month Status Issue
1 ready
2 not_ready Missing Coverage
3 not_ready Unexpected Coverage
4 not_ready Unexpected coverage end date. Coverage still active, but carrier end date is before renewal date.
5 not_ready Unexpected coverage end date. Coverage dropped, but carrier end date is after renewal date.
6 not_ready Unexpected open enrollment dates
7 not_ready Inconsistent plan quantities

Pagination

Code Sample

curl -X GET
 --header "Content-Type: application/json"
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups?page_size=5&offset=5

Example Response

{
    "meta": {
        "offset": 5,
        "page_num": 2,
        "page_size": 5,
        "total_records": 60
    },
    "response": [
        {
            "id": "049c6ac3-3cf2-4d99-b781-aaa9aa846cb2",
            "version": "0dce45a0-089c-470a-a15b-58080159d407",
            "created": 1557862286,
            "modified": 1557862286,
            "organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
            "name": "Company 1",
            "sic_code": "2121"
            },
        {
            "id": "06108fa4-ce4e-47d9-bb2f-8aec0553f9e5",
            "version": "0e418c78-a9df-4fd5-9d32-639015eff637",
            "created": 1558451441,
            "modified": 1558451441,
            "organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
            "name": "Company 2",
            "sic_code": "2121"
            },
        {
            "id": "0bbb8ebb-26a8-4724-99d3-5c76c198be0a",
            "version": "84f253a4-ce07-4601-ac13-75b410c4a94b",
            "created": 1557862304,
            "modified": 1557862304,
            "organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
            "name": "Company 3",
            "sic_code": "2121"
            },
        {
            "id": "0dc7c14f-4184-4a35-ab67-ff127bfd7bc9",
            "version": "ff9d3603-45a0-46f2-b035-96fa777255b3",
            "created": 1557868278,
            "modified": 1557868278,
            "organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
            "name": "Company 4",
            "sic_code": "2121"
            },
        {
            "id": "12a2f910-8959-4076-9907-2050945da309",
            "version": "db3cf8d5-185a-49ff-80e3-ee3afe56f935",
            "created": 1557329939,
            "modified": 1557329939,
            "organization_id": "bb728722-18b8-4b9b-8613-45bedb6040d4",
            "name": "Company 5",
            "sic_code": "2121"
        }
    ]
}

All resources that support bulk fetching a "list" of objects share a common structure and take the optional arguments page_size and offset.

Query Parameters

page_size Number of records returned in the list, defaults to 20, must be at least 5, cannot exceed 100
offset The entry in the list at which to begin returning results, defaults to 0

Paginated Result

meta
  • 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.

Changes Over Time

Several of the Noyo models track data elements that change over time. For example, a group plan may only be available for one enrollment year but then it could be discontinued, or a member might enroll in the same life plan for multiple years but their coverage volume could change after each open enrollment period.

The Noyo API endpoints allow callers to query for these models with an optional target effective_date. This will allow you to easily answer questions like "What was the status of this user's enrollment one month ago?" or "What volume of coverage did the member elect last year?". The group carrier configuration, group enrollment, group plan, and individual enrollment models all support this behavior.

The API will return our best approximation of the status of a record as-of the requested effective_date, given that we may not be able to reconstruct the complete history of a record for all carriers. The default behavior when no effective_date is provided is to return the state of the record as-of today.

Example: Individual Enrollments

Suppose you sent Noyo a member request to enroll an employee in coverage and their individual enrollment was created with an effective_start_date for coverage on 7/1/2020.

Querying with an effective_date prior to the effective_start_date

Code Sample

curl -X GET
 --header "Content-Type: application/json"
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/individual_enrollments/ac96373c-fcb2-4cb5-af1f-52d2afeace01?effective_date=2020-06-15

Example Response

{
    "id": "ac96373c-fcb2-4cb5-af1f-52d2afeace01",
    "version": "fe8c33aa-2721-4097-9695-63512f8ac90a",
    "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
    "line_of_coverage": "medical",
    "status": "pending",
    "individual_type": "employee",
    "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
    "enroll_data": {},
    "effective_start_date": "2020-07-01",
    "effective_end_date": "2021-07-01",
    "individual_enrollment_configuration": {},
    "created": 1592141191,
    "modified": 1592141191
}

With an effective_date prior to the resource's effective_start_date, the individual enrollment in the response should have a pending status. It's also possible that no record will be returned if Noyo did not have any record of this enrollment prior to the effective_start_date, as may be the case in a broker of record change.























Querying with an effective_date after the effective_start_date

Code Sample

curl -X GET
 --header "Content-Type: application/json"
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/individual_enrollments/ac96373c-fcb2-4cb5-af1f-52d2afeace01?effective_date=2020-07-15

Example Response

{
    "id": "ac96373c-fcb2-4cb5-af1f-52d2afeace01",
    "version": "fe8c33aa-2721-4097-9695-63512f8ac90a",
    "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
    "line_of_coverage": "medical",
    "status": "active",
    "individual_type": "employee",
    "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
    "enroll_data": {},
    "effective_start_date": "2020-07-01",
    "effective_end_date": "2021-07-01",
    "individual_enrollment_configuration": {},
    "created": 1592141191,
    "modified": 1592141191
}

After the member request is completed and the member is confirmed active on coverage, querying for the individual enrollment with an effective_date after the resource's effective_start_date should return a status of active. As long as we have not received a termination or a QLE request to remove this coverage, you will find that the response returns an active status even for dates far in the future.

























Querying with an effective_date after the effective_end_date

Code Sample

curl -X GET
 --header "Content-Type: application/json"
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/individual_enrollments/ac96373c-fcb2-4cb5-af1f-52d2afeace01?effective_date=2020-11-01

Example Response

{
    "id": "ac96373c-fcb2-4cb5-af1f-52d2afeace01",
    "version": "fe8c33aa-2721-4097-9695-63512f8ac90a",
    "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
    "line_of_coverage": "medical",
    "status": "terminated",
    "individual_type": "employee",
    "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
    "enroll_data": {},
    "effective_start_date": "2020-07-01",
    "effective_end_date": "2020-09-30",
    "individual_enrollment_configuration": {},
    "created": 1592141191,
    "modified": 1592181928
}

Suppose you later send Noyo a termination member request for this employee and their individual enrollment is updated with a coverage effective_end_date of 9/30/2020.

After the member request is completed and the member coverage is confirmed to be terminated on 9/30/2020, querying for the individual enrollment with an effective_date after the resource's effective_end_date should return a status of terminated.

OpenAPI Specs

Noyo now offers OpenAPI interfaces of our APIs. You may use the links below to check out the JSON files for Noyo services. These may be used to pull into tools to understand the API interface better, build API clients, etc.

Fulfillment Service

Integration Guide

Mapping for Enrollment Management

The Noyo API is able to provide a level of correctness and visibility by working based off unique identifiers for things like Plans, Employees, and Dependents. This ensures that requests coming in from the API can go through extensive validation to ensure the correct actions are taken with each carrier. From an integration standpoint this requires some amount of mapping between the entities in the Noyo system and the entities in your system. This guide serves as a blueprint for how you can go about that mapping process and then proceed to making ongoing requests to the API.

Two Mapping Flows

There are two types of mapping flows with the Noyo API depending on whether the group has existing coverage with the insurance carrier or is getting enrolled for the very first time with that carrier.

Existing Group Setup

In this case the Noyo API is populated with information about the group's plans, employees, dependents and enrollments already (pulled directly from the carrier system). You are responsible for mapping these entities and their unique IDs to the corresponding entities in your system.

You should create a function / routine / process / etc. that for a given group can perform the following operations:

Noyo Existing Group Setup Flow

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:

Noyo New Group Setup Flow

Mapping Groups

You can query a list of all groups in the API using the Get Groups endpoint. Remember you can use the pagination query parameters to go through more groups at one time. You should be able to match up the group using the following fields:

Field Description
name Always present
dba_name Optional, Doing Business As name

Alternatively, in order to identify a group by a carrier-specific ID, use the group list endpoint and query using a carrier_id and carrier_group_id combination. This may be a helpful mapping if these are IDs you store. See our carrier specs for what carrier-specific ID is used for each carrier.

Mapping Employees

You can query a list of all employees within a group using the Filtering Employees in a Group endpoint. You can optionally specify filters in the query parameters for first_name, last_name, and date_of_birth. You should be able to match up the employee using the following fields:

Field Description
person.first_name Always present, make sure to map agnostic of letter casing
person.last_name Always present, make sure to map agnostic of letter casing
person.date_of_birth Always present, always in the format YYYY-MM-DD
person.ssn Optional, not all carriers store this in their system

Mapping Dependents

Once you have mapped the employee you can query the dependents that belong to that employee with the Get Dependents endpoint. You should be able to match up the dependents using the following fields:

Field Description
person.first_name Always present, make sure to map agnostic of letter casing
person.last_name Always present, make sure to map agnostic of letter casing
person.date_of_birth Always present, always in the format YYYY-MM-DD
person.ssn Optional, not all carriers store this in their system
relationship Always present

Mapping Plans

Map a group's plans using the group plans endpoint. Plans can be matched by some combination of line of coverage, name, and other attributes included in the API response. The API will return plans associated with a group enrollment for its carrier and effective dates. Group enrollment data should also be mapped to your data, especially so that correct open enrollment dates can be recorded. A common hierarchy of group enrollments and group plans looks like this:

Common Group Enrollment Hierarchy

Enrolling During New Group Setup

During the New Group Setup process, the Employees and Dependents will not yet exist and it will be your responsibility to create them using the Create Employee and Create Dependent endpoints. After you make the create requests you should save the IDs of the created employees and dependents into your system.

After you have created these you can send an Open Enrollment Member Request for each employee which includes information about what plan(s) the employee and their dependents would like to enroll in.

Group Structure Mapping

Noyo provides a tool within the dashboard for group structure and plan name mapping. To use the Group Structure Mapping tool for a group already in the Noyo system, just submit the group’s account structure information with the Account Structure object. After the account structure is submitted and the group is successfully connected to a new carrier, users can access the Group Structure Mapping tool and begin creating rules to classify members and plans.

Ongoing Member Requests

After the mapping process completes for each a group (either through the existing or new group setup flow) you will be able to start making ongoing Member Requests to the API. This should be very straightforward after the mapping process is completed because the payloads consist largely of IDs and the validation will prevent you from sending incorrect or incomplete data to the API. More details on creating API calls for each Member Request can be found here:

Group Installation

The Group Installation product ensures that newly sold groups are entered correctly into the insurance carrier's system. This product is currently in a closed beta, but please contact your Customer Success Manager if you'd like to learn more about how to participate.

Group Connections

Group connections enable you to set up a carrier connection through Noyo for a group that you administer. To create a group connection, the group must already be installed in the carrier’s system, and Noyo must have permission to manage enrollments for the group.

Note: If you used Noyo’s beta Group Installation product to install the group with the carrier, you do not need to set up a connection as well.

Group Connection Statuses

Group connections will move through several different statuses as it passes through Noyo's system and is sent to the carrier.

Key Description
created This status is the result of the initial submission (POST). We have not yet verified the current state of the carrier’s system.
processing We are communicating the group connection to the carrier involved.
noyo_review Noyo is actively resolving an issue with the group connection; no action is needed from you.
waiting_on_carrier The group connection has been submitted and the carrier is processing it.
carrier_authorization There was an authorization problem when pulling group data from a carrier. It may require you to reach out to the carrier to resolve.
action_required Action from you is required for successful processing. Notes are listed in the setup_result field on the group connection object.
unable_to_connect The carrier was unable to install this group connection. Notes are listed in the setup_result field on the group connection object.
completed The group connection has been completed and Noyo now has the ability to manage enrollment and eligibility changes for the specific group that is installed on the carrier’s system

This diagram shows the potential paths for a group connection.

Noyo Group Connection Statuses

Create Group Connection

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/group_connections

Body Parameter


{
    "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
    "federal_ein": "123456789",
    "group_data": {
        "carrier_group_id": "10000000",
        "group_name": "Test Company"
    }
}

Example Response

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
    "created": 1557329939,
    "modified": 1557329939,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
    "group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
    "request_type": "initial",
    "status": "created",
    "group_data": {
        "carrier_group_id": "10000000",
        "group_name": "Test Company"
    }
}

Create a new connection for a brand new group with a given carrier

Request Body

carrier_id* uuid Unique identifier of the carrier in Noyo
federal_ein string Federal Employer Identification Number for the new group/company
group_data* object
  • carrier_group_id*: Unique identifier for the group in the carrier system
  • group_name*: Name for the group in the Noyo system
  • broker_federal_ein: Federal Employer Identification Number for the group's broker. Only needed where relevant for carrier authorization

Create Group Connection Response

id* uuid Unique identifier of the group connection in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
completed timestamp Timestamp indicating when a group connection was marked as completed.
organization_id* uuid Unique identifier of the platform or broker organization in Noyo
group_id uuid ID of associated group model
carrier_id* uuid Unique identifier of the carrier in Noyo
request_type* string Type of the group connection
status* string Status of the group connection. One of: action_required, carrier_authorization, completed, created, noyo_review, processing, unable_to_connect, waiting_on_carrier
group_data* object
  • carrier_group_id*: Unique identifier for the group in the carrier system
  • group_name*: Name for the group in the Noyo system
setup_result* object More information about the result of the group connection

Error Cases

Error Name Response Status Code Description
Duplicate 409 Submitting a duplicate group connection (identical carrier_id and carrier_group_id as another group connection) will result in a 409 conflict error.
Missing Fields 422 If any required fields are missing, the request will result in a 422.
Carrier Group ID Format 422 Submitting a carrier_group_id that violates carrier-specific formatting will result in a 422 error. Ask Noyo for specifics on different carrier group ID formats.

Retry Group Connection

If a group connection has gone through its retry attempts and is in an unable_to_connect state, you can retry the group connection later through this API endpoint. When you retry a group connection, you will have the option to update the unique identifier for the carrier's group (carrier_group_id). Retrying a group connection keeps the id that was previously used to identify the group connection, and sends off the same request with any updated information to the carrier. This retry will update the status of the group connection to processing.

Retry Group Connection Request

Code Sample

curl -X PUT
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/group_connections/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/retry

Body Parameter


{
    "carrier_group_id": "10000001"
}

Example Response

{
    "id": "5e20ea6a-8027-464a-941a-867c115c846d",
    "version": "608c6f37-5945-4987-b247-0b5acdf85034",
    "created": 1667866198,
    "modified": 1667866198,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
    "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
    "request_type": "incremental",
    "status": "processing",
    "group_data": {
        "carrier_group_id": "10000001"
    }
}

Retry a carrier connection for an existing group

Path Parameters

connection_id The unique identifier of the group connection that needs to be reprocessed

Request Body

carrier_group_id string Unique identifier for the group in the carrier system

Retry Group Connection Response

id* uuid Unique identifier of the group connection in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
completed timestamp Timestamp indicating when a group connection was marked as completed.
organization_id* uuid Unique identifier of the platform or broker organization in Noyo
group_id uuid ID of associated group model
carrier_id* uuid Unique identifier of the carrier in Noyo
request_type* string Type of the group connection
status* string Status of the group connection. One of: action_required, carrier_authorization, completed, created, noyo_review, processing, unable_to_connect, waiting_on_carrier
group_data* object
  • carrier_group_id*: Unique identifier for the group in the carrier system
  • group_name*: Name for the group in the Noyo system
setup_result* object More information about the result of the group connection

Adding Another Carrier

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/group_connections

Body Parameter


{
    "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
    "group_data": {
        "carrier_group_id": "10000000"
    }
}

Example Response

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
    "created": 1557329939,
    "modified": 1557329939,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
    "group_id": "47c07963-2e34-4da2-86b4-cbc3c57111c1",
    "request_type": "incremental",
    "status": "created",
    "group_data": {
        "carrier_group_id": "10000000"
    }
}

Create a new carrier connection for an existing group

Path Parameters

group_id The unique identifier of the group for which you would like to add a carrier connection
carrier_id* uuid Unique identifier of the carrier in Noyo
group_data* object
  • carrier_group_id*: Unique identifier for the group in the carrier system
  • broker_federal_ein: Federal Employer Identification Number for the group's broker. Only needed where relevant for carrier authorization

Get Single Group Connection

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/group_connections/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1

Example Response

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
    "created": 1557329939,
    "modified": 1557392400,
    "completed": 1557392400,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "group_id": "9e629e41-c706-4efd-9fbb-1ff2573fc67e",
    "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
    "request_type": "initial",
    "status": "completed",
    "group_data": {
        "carrier_group_id": "10000000",
        "group_name": "Test Company"
    },
    "setup_result": {}
}

Returns the latest status of a single group connection based on the ID provided.

Path Parameters

connection_id The unique identifier of the group connection you would like to view

Get Single Group Connection Response

Setup Result

The setup_result's structure will depend on the group connection's status.

If in noyo_review, action_required, waiting_on_carrier, or unable_to_connect statuses, it may contain an error string that gives further details about the specific issue involved.

For other statuses, the setup_result will be empty.

id* uuid Unique identifier of the group connection in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
completed timestamp Timestamp indicating when a group connection was marked as completed.
organization_id* uuid Unique identifier of the platform or broker organization in Noyo
group_id uuid ID of associated group model
carrier_id* uuid Unique identifier of the carrier in Noyo
request_type* string Type of the group connection
status* string Status of the group connection. One of: action_required, carrier_authorization, completed, created, noyo_review, processing, unable_to_connect, waiting_on_carrier
group_data* object
  • carrier_group_id*: Unique identifier for the group in the carrier system
  • group_name*: Name for the group in the Noyo system
setup_result* object More information about the result of the group connection

Get Group Connections

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/group_connections

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
            "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
            "created": 1557329939,
            "modified": 1557392400,
            "completed": 1557392400,
            "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
            "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
            "request_type": "initial",
            "status": "processing",
            "group_data": {
                "carrier_group_id": "10000000",
                "group_name": "Test Company"
            }
        }
    ]
}

Returns a list of all group connections.

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
status Status of the group connection for which you would like to filter. Multiple statuses can be used, separated by a comma.
carrier_id The unique identifier of the carrier for which you would like to view group connection requests
organization_id The unique identifier of the organization for which you would like to view group connection requests
sort_by The attribute on which to sort the group connections
sort_direction Either asc or desc, to denote the data's direction

Get All Group Connections Response

meta* object
  • 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 connection in Noyo
  • version*: Current version of the record
  • created*: The date the record was created
  • modified*: The date the record was last updated
  • completed: Timestamp indicating when a group connection was marked as completed.
  • organization_id*: Unique identifier of the platform or broker organization in Noyo
  • group_id: ID of associated group model
  • carrier_id*: Unique identifier of the carrier in Noyo
  • request_type*: Type of the group connection
  • status*: Status of the group connection. One of: action_required, carrier_authorization, completed, created, noyo_review, processing, unable_to_connect, waiting_on_carrier
  • group_data*:
    • carrier_group_id*: Unique identifier for the group in the carrier system
    • group_name*: Name for the group in the Noyo system
  • setup_result*: More information about the result of the group connection

Group Connections in a Group

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2ce3b54a-2535-4803-b218-e6b44081d418/group_connections

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
            "version": "9906b5d2-e76d-4bad-ba4c-8ce90b6b867b",
            "created": 1557329939,
            "modified": 1557392400,
            "completed": 1557392400,
            "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
            "carrier_id": "8fac0992-933a-4743-8dab-0d606ef2569e",
            "request_type": "initial",
            "status": "processing",
            "group_data": {
                "carrier_group_id": "10000000",
                "group_name": "Test Company"
            }
        }
    ]
}

Returns a list of all group connections for a given group ID.

Path Parameters

group_id The unique identifier of the associated group in Noyo

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
sort_by The attribute on which to sort the group connections
sort_direction Either asc or desc, to denote the data's direction
status Status of group connection for which you would like to filter. Multiple statuses can be used, separated by a comma.

Group Structure Mapping

Benefits platforms can use Noyo’s tool to map account and plan information between their systems and the carrier’s. You will need to submit an account structure for each group that will be mapped; this information populates the conditions in the Group Structure Mapping tool.

Create Account Structure

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/3e366930-df4d-11eb-ba80-0242ac130004/platform_account_structures

Body Parameter


{
    "account_structure": {
        "account_structure_fields": [
            {
                "field_name": "BranchName",
                "field_type": "string",
                "existing_value_set": [
                    "North Branch",
                    "HQ",
                    "Springfield"
                ]
            }
        ],
        "plans": {
            "group_medical_plans": [
                "Medical Plan A",
                "Medical Plan B"
            ],
            "group_dental_plans": [
                "Dental Plan Low",
                "Dental Plan High"
            ]
        }
    },
    "start_date": "2021-01-12"
}

Example Response

{
    "id": "3e366930-df4d-11eb-ba80-0242ac130004",
    "version": "5200a894-81c5-4c41-8519-86c32e9a9965",
    "created": 1626281253,
    "modified": 1626281253,
    "group_id": "3e366930-df4d-11eb-ba80-0242ac130004",
    "account_structure": {
        "account_structure_fields": [
            {
                "field_name": "BranchName",
                "field_type": "string",
                "existing_value_set": [
                    "North Branch",
                    "HQ",
                    "Springfield"
                ]
            }
        ],
        "plans": {
            "group_medical_plans": [
                "Medical Plan A",
                "Medical Plan B"
            ],
            "group_dental_plans": [
                "Dental Plan Low",
                "Dental Plan High"
            ]
        }
    }
}

Create a new Platform Account Structure

Path Parameters

group_id Unique identifier of the associated group in the Noyo system

Request Body

account_structure* object
  • account_structure_fields:
    • field_name*: The name of the field
    • field_type*: The data type of this field. One of: boolean, date, decimal, integer, string
    • existing_value_set*: All distinct values that are represented in the group for this field
  • plans:
    • group_medical_plans: List of medical plan names for the group
    • group_dental_plans: List of dental plan names for the group
    • group_vision_plans: List of vision plan names for the group
    • group_life_plans: List of life plan names for the group
    • group_add_plans: List of AD&D plan names for the group
    • group_std_plans: List of short-term disability plan names for the group
    • group_ltd_plans: List of long-term disability plan names for the group
    • group_accident_plans: List of accident plan names for the group
    • group_critical_illness_plans: List of critical illness plan names for the group
    • group_cancer_plans: List of cancer plan names for the group
    • group_hospital_indemnity_plans: List of hospital indemnity plan names for the group
start_date date Effective start date of the record, defaults to today
end_date date Effective end date of the record

Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
account_structure* object
  • account_structure_fields:
    • field_name*: The name of the field
    • field_type*: The data type of this field. One of: boolean, date, decimal, integer, string
    • existing_value_set*: All distinct values that are represented in the group for this field
  • plans:
    • group_medical_plans: List of medical plan names for the group
    • group_dental_plans: List of dental plan names for the group
    • group_vision_plans: List of vision plan names for the group
    • group_life_plans: List of life plan names for the group
    • group_add_plans: List of AD&D plan names for the group
    • group_std_plans: List of short-term disability plan names for the group
    • group_ltd_plans: List of long-term disability plan names for the group
    • group_accident_plans: List of accident plan names for the group
    • group_critical_illness_plans: List of critical illness plan names for the group
    • group_cancer_plans: List of cancer plan names for the group
    • group_hospital_indemnity_plans: List of hospital indemnity plan names for the group

Get Account Structure by Group

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2705bb9f-3c90-4400-a4e7-0bc9d48e677c/platform_account_structures

Example Response

{
    "id": "2705bb9f-3c90-4400-a4e7-0bc9d48e677c",
    "version": "7a2b0437-4027-4251-9e71-85384c0eb1c9",
    "group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
    "account_structure": {
        "account_structure_fields": [
            {
                "field_name": "BranchName",
                "field_type": "string",
                "existing_value_set": [
                    "North Branch",
                    "HQ",
                    "Springfield"
                ]
            }
        ],
        "plans": {
            "group_medical_plans": [
                "Medical Plan A",
                "Medical Plan B"
            ],
            "group_dental_plans": [
                "Dental Plan Low",
                "Dental Plan High"
            ]
        }
    }
}

Retrieve a Platform Account Structure by Group

Path Parameters

group_id The unique identifier of the group you want to get a platform account structure for

Query Parameters

effective_date The relative date on which to view the state of the record

Get Account Structure by Group Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
account_structure* object
  • account_structure_fields:
    • field_name*: The name of the field
    • field_type*: The data type of this field. One of: boolean, date, decimal, integer, string
    • existing_value_set*: All distinct values that are represented in the group for this field
  • plans:
    • group_medical_plans: List of medical plan names for the group
    • group_dental_plans: List of dental plan names for the group
    • group_vision_plans: List of vision plan names for the group
    • group_life_plans: List of life plan names for the group
    • group_add_plans: List of AD&D plan names for the group
    • group_std_plans: List of short-term disability plan names for the group
    • group_ltd_plans: List of long-term disability plan names for the group
    • group_accident_plans: List of accident plan names for the group
    • group_critical_illness_plans: List of critical illness plan names for the group
    • group_cancer_plans: List of cancer plan names for the group
    • group_hospital_indemnity_plans: List of hospital indemnity plan names for the group

Get Account Structure By ID

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/platform_account_structures/2705bb9f-3c90-4400-a4e7-0bc9d48e677c

Example Response

{
    "id": "2705bb9f-3c90-4400-a4e7-0bc9d48e677c",
    "version": "7a2b0437-4027-4251-9e71-85384c0eb1c9",
    "group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
    "account_structure": {
        "account_structure_fields": [
            {
                "field_name": "BranchName",
                "field_type": "string",
                "existing_value_set": [
                    "North Branch",
                    "HQ",
                    "Springfield"
                ]
            }
        ],
        "plans": {
            "group_medical_plans": [
                "Medical Plan A",
                "Medical Plan B"
            ],
            "group_dental_plans": [
                "Dental Plan Low",
                "Dental Plan High"
            ]
        }
    }
}

Retrieve a Platform Account Structure

Path Parameters

platform_account_structure_id The unique identifier of the platform account structure to be retrieved.

Query Parameters

effective_date The relative date on which to view the state of the record

Get Account Structure Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
account_structure* object
  • account_structure_fields:
    • field_name*: The name of the field
    • field_type*: The data type of this field. One of: boolean, date, decimal, integer, string
    • existing_value_set*: All distinct values that are represented in the group for this field
  • plans:
    • group_medical_plans: List of medical plan names for the group
    • group_dental_plans: List of dental plan names for the group
    • group_vision_plans: List of vision plan names for the group
    • group_life_plans: List of life plan names for the group
    • group_add_plans: List of AD&D plan names for the group
    • group_std_plans: List of short-term disability plan names for the group
    • group_ltd_plans: List of long-term disability plan names for the group
    • group_accident_plans: List of accident plan names for the group
    • group_critical_illness_plans: List of critical illness plan names for the group
    • group_cancer_plans: List of cancer plan names for the group
    • group_hospital_indemnity_plans: List of hospital indemnity plan names for the group

Edit Account Structure

Code Sample

curl -X PUT
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/platform_account_structures/3e366930-df4d-11eb-ba80-0242ac130004/5200a894-81c5-4c41-8519-86c32e9a9965

Body Parameter


{
    "account_structure": {
        "account_structure_fields": [
            {
                "field_name": "BranchName",
                "field_type": "date",
                "existing_value_set": [
                    "North Branch",
                    "HQ",
                    "Springfield"
                ]
            }
        ],
        "plans": {
            "group_medical_plans": [
                "Medical Plan A",
                "Medical Plan B"
            ],
            "group_dental_plans": [
                "Dental Plan Low",
                "Dental Plan High"
            ]
        }
    }
}

Example Response

{
    "id": "3e366930-df4d-11eb-ba80-0242ac130004",
    "version": "5200a894-81c5-4c41-8519-86c32e9a9965",
    "created": 1557512389,
    "modified": 1543215342,
    "group_id": "3e366930-df4d-11eb-ba80-0242ac130004",
    "account_structure": {
        "account_structure_fields": [
            {
                "field_name": "BranchName",
                "field_type": "date",
                "existing_value_set": [
                    "North Branch",
                    "HQ",
                    "Springfield"
                ]
            }
        ],
        "plans": {
            "group_medical_plans": [
                "Medical Plan A",
                "Medical Plan B"
            ],
            "group_dental_plans": [
                "Dental Plan Low",
                "Dental Plan High"
            ]
        }
    }
}

Edit a platform account structure based on the ID provided. The version parameter must match the latest platform account structure version.

Path Parameters

platform_account_structure_id Unique identifier of the platform account structure in the Noyo system
version Current version of the model

Query Parameters

effective_date The relative date on which to view the state of the record

Request Body

account_structure* object
  • account_structure_fields:
    • field_name*: The name of the field
    • field_type*: The data type of this field. One of: boolean, date, decimal, integer, string
    • existing_value_set*: All distinct values that are represented in the group for this field
  • plans:
    • group_medical_plans: List of medical plan names for the group
    • group_dental_plans: List of dental plan names for the group
    • group_vision_plans: List of vision plan names for the group
    • group_life_plans: List of life plan names for the group
    • group_add_plans: List of AD&D plan names for the group
    • group_std_plans: List of short-term disability plan names for the group
    • group_ltd_plans: List of long-term disability plan names for the group
    • group_accident_plans: List of accident plan names for the group
    • group_critical_illness_plans: List of critical illness plan names for the group
    • group_cancer_plans: List of cancer plan names for the group
    • group_hospital_indemnity_plans: List of hospital indemnity plan names for the group
effective_date date Effective date for target record to update, defaults to today

Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
account_structure* object
  • account_structure_fields:
    • field_name*: The name of the field
    • field_type*: The data type of this field. One of: boolean, date, decimal, integer, string
    • existing_value_set*: All distinct values that are represented in the group for this field
  • plans:
    • group_medical_plans: List of medical plan names for the group
    • group_dental_plans: List of dental plan names for the group
    • group_vision_plans: List of vision plan names for the group
    • group_life_plans: List of life plan names for the group
    • group_add_plans: List of AD&D plan names for the group
    • group_std_plans: List of short-term disability plan names for the group
    • group_ltd_plans: List of long-term disability plan names for the group
    • group_accident_plans: List of accident plan names for the group
    • group_critical_illness_plans: List of critical illness plan names for the group
    • group_cancer_plans: List of cancer plan names for the group
    • group_hospital_indemnity_plans: List of hospital indemnity plan names for the group

Policy Management

Creating Member Requests

Member requests and member transactions are the heart and soul of the Noyo group benefits API. They represent the core operations you want to carry out on behalf of members (employees and dependents) at one or many carriers. The following types of member requests are supported by the Noyo platform:

Each member request is attached to an employee, changes you wish to make to dependents are done via a member request attached to the employee. Each member request will contain many member transactions, which represent smaller sub-operations being carried out at a carrier partner. For example, a New Hire Enrollment member request may result in two member transactions: one to add medical coverage at Carrier A, and a second to add dental and vision coverage at Carrier B. More details about member requests and associated transactions follows.

Member Request Statuses

The following are possible member request statuses that you might receive when fetching member request(s) from the API.

Key Description
processing We are communicating the member request changes to the carrier(s) involved.
completed A request is completed after all transactions with all carriers have been processed. This may take seconds or longer, depending on the carrier and request type. The results of the member request have been reflected in the carrier system at this point.
failed Requests will only move to the failed status if for an unexpected reason we were unable to fulfill at the carrier. You should expect very few member requests to transition into this status.
canceled Requests will be moved to the canceled status if a subsequent member request supersedes it.

As far as state transitions, expect the progression to be linear, from processing to either completed, failed, or canceled. Once in completed, failed, or canceled a member request will not move back to processing. The proper response from a failed member request, if not desired, would be to recreate the attempted changes in a new member request.

Renewal Readiness

Groups approaching open enrollment will typically contact the carrier directly to notify them of any new plans or group level modifications for their renewal period. Noyo will attempt to detect any changes in the carrier system and update our coverage records to match, but since those decisions are sent directly to the carrier, we may not know whether any changes found were intentional or whether additional updates are still in progress and need to complete before the carrier can accept member level open enrollment requests for the group.

The Renewal Readiness object allows you to tell us about the expected renewal changes for a group, so that Noyo can confirm when a carrier has installed everything correctly and is ready to receive member requests for the new plan year. A renewal decision record is defined by the target renewal date, and includes the lines of coverage and plans that are expected to be active for that renewal date. Noyo will then continuously check the carrier's system to confirm that your decisions have been processed. If expectations are met, we will update the status of the renewal readiness record to ready and you can start sending member requests. Otherwise, we will update the status to not_ready and inform you of any remaining issues.

Renewal Decision Statuses

Renewal decisions will move through several different statuses before and during open enrollment:

Key Description
submitted This status is the result of the initial submission (POST). We have not yet verified the current state of the carrier’s system.
not_ready There is a difference between your submitted renewal decision and the carrier's current state. We will supply an array of issues in a response body.
ready Your renewal decision reflects what is shown in the carrier’s system. Open enrollment member requests will work as expected at this point.

Renewal decisions will start with a submitted status, and then progress to ready or not_ready. The status can switch from ready to not_ready if we detect a carrier update that regresses their system to a state that is different from your decisions. The status can also switch from not_ready to ready if detected differences are resolved.

Get Renewal Decisions by Group

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/renewal_decisions

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
            "version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
            "created": 1557862286,
            "modified": 1557862286,
            "status": "not_ready",
            "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
            "renewal_date": "2022-01-01",
            "body": {
                "carriers": [
                    {
                        "carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
                        "lines_of_coverage": {
                            "medical": {
                                "open_enrollment_start_date": "2022-01-01",
                                "open_enrollment_end_date": "2022-01-31",
                                "plans": [
                                    {
                                        "plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
                                        "name": "Select Plus PPO HDHP Gold BRJJ /C38"
                                    },
                                    {
                                        "plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
                                        "name": "Select Plus PPO HDHP Silver BRJJ /C38"
                                    },
                                    {
                                        "plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
                                        "name": "Select Plus PPO HDHP Bronze BRJJ /C38"
                                    }
                                ]
                            },
                            "dental": {
                                "open_enrollment_start_date": "2022-01-01",
                                "open_enrollment_end_date": "2022-01-31",
                                "plans": [
                                    {
                                        "plan_id": "44bc0f4a-0a94-11ec-9a03-0242ac130003",
                                        "name": "Dental Plus Plan"
                                    }
                                ]
                            }
                        }
                    }
                ]
            },
            "issues": [
                {
                    "level": "error",
                    "message": "Life open enrollment start date is 2021-08-01 in carrier system"
                },
                {
                    "level": "error",
                    "message": "LTD Plan not available yet in carrier system"
                }
            ]
        }
    ]
}

Returns all renewal decisions for a group. This includes the status, which determines whether the carrier is ready to accept member requests for the new plan year. If the status is not_ready, Noyo will return one or more issues, each with a level and message.

Path Parameters

group_id The unique identifier of the group for which you are retrieving renewal decisions

Query Parameters

renewal_date Renewal date to filter by, exact match

Get Renewal Decisions by Group Response

meta* object
  • 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 record in Noyo
  • version*: Current version of the record
  • created*: The date the record was created
  • modified*: The date the record was last updated
  • status*: Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted
  • group_id*: Unique identifier of the group in Noyo
  • renewal_date*: The start date for the new enrollment year when all coverage changes and decisions should become active
  • body*:
    • carriers*:
      • carrier_id*: Unique identifier of the carrier in Noyo
      • lines_of_coverage:
        • medical:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • dental:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • vision:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • life:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • add:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • std:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • ltd:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • accident:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • critical_illness:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • cancer:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
        • hospital_indemnity:
          • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
          • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
          • plans:
            • plan_id: Unique ID of a group plan that exists in the Noyo system
            • name: Name of the group plan
  • issues*:
    • level*: The level or severity of the issue found. One of: error, warning
    • message*: Message describing the issue found and any steps to resolve
    • carrier_id: Unique identifier of the associated carrier in Noyo
    • line_of_coverage: Line of coverage related to the issue

Get Renewal Decision by ID

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/renewal_decisions/4093a441-d4c8-4c8a-24d1-e7a132fb1bc2

Example Response

{
    "id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
    "version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
    "created": 1557862286,
    "modified": 1557862286,
    "status": "not_ready",
    "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
    "renewal_date": "2022-01-01",
    "body": {
        "carriers": [
            {
                "carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
                "lines_of_coverage": {
                    "medical": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
                                "name": "Select Plus PPO HDHP Gold BRJJ /C38"
                            },
                            {
                                "plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
                                "name": "Select Plus PPO HDHP Silver BRJJ /C38"
                            },
                            {
                                "plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
                                "name": "Select Plus PPO HDHP Bronze BRJJ /C38"
                            }
                        ]
                    },
                    "dental": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "81803f12-0a96-11ec-9a03-0242ac130003",
                                "name": "Dental Plus Plan"
                            }
                        ]
                    }
                }
            }
        ]
    },
    "issues": [
        {
            "level": "error",
            "message": "Life open enrollment start date is 2021-08-01 in carrier system"
        },
        {
            "level": "error",
            "message": "LTD Plan not available yet in carrier system"
        }
    ]
}

Returns a renewal decision by ID.

Path Parameters

group_id The unique identifier of the group for which you are retrieving a renewal decision
renewal_decision_id The unique identifier of the renewal decision you want to retrieve

Get Renewal Decisions by ID Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
status* string Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted
group_id* uuid Unique identifier of the group in Noyo
renewal_date* date The start date for the new enrollment year when all coverage changes and decisions should become active
body* object
  • carriers*:
    • carrier_id*: Unique identifier of the carrier in Noyo
    • lines_of_coverage:
      • medical:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • dental:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • vision:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • life:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • add:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • std:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • ltd:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • accident:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • critical_illness:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • cancer:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • hospital_indemnity:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
issues* array
  • level*: The level or severity of the issue found. One of: error, warning
  • message*: Message describing the issue found and any steps to resolve
  • carrier_id: Unique identifier of the associated carrier in Noyo
  • line_of_coverage: Line of coverage related to the issue

Create Renewal Decisions

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/renewal_decisions

Body Parameter


{
    "renewal_date": "2022-01-01",
    "body": {
        "carriers": [
            {
                "carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
                "lines_of_coverage": {
                    "medical": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "818e52d4-6c34-4914-b716-a3047c85e468"
                            },
                            {
                                "plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2"
                            },
                            {
                                "name": "Select Plus PPO HDHP Bronze BRJJ /C38"
                            }
                        ]
                    },
                    "dental": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "name": "Dental Plus Plan"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

Example Response

{
    "id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
    "version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
    "created": 1557862286,
    "modified": 1557862286,
    "status": "submitted",
    "group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
    "renewal_date": "2022-01-01",
    "body": {
        "carriers": [
            {
                "carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
                "lines_of_coverage": {
                    "medical": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
                                "name": "Select Plus PPO HDHP Gold BRJJ /C38"
                            },
                            {
                                "plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
                                "name": "Select Plus PPO HDHP Silver BRJJ /C38"
                            },
                            {
                                "plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
                                "name": "Select Plus PPO HDHP Bronze BRJJ /C38"
                            }
                        ]
                    },
                    "dental": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "44bc0f4a-0a94-11ec-9a03-0242ac130003",
                                "name": "Dental Plus Plan"
                            }
                        ]
                    }
                }
            }
        ]
    },
    "issues": []
}

Create a new renewal decision for a given renewal date.

Path Parameters

group_id The unique identifier of the group for which you are creating a new renewal decision

Send Configurations

The renewal decision may be submitted in a few different configurations:

Permitted Time Window

A renewal decision may be created with a renewal date up to 30 days ago, and up to 6 months in the future. Both of these constraints are relative to the date the request is sent.

Request Body

renewal_date* date The start date for the new enrollment year when all coverages should be active
body* object
  • carriers*:
    • carrier_id*: Unique identifier of the carrier in Noyo
    • lines_of_coverage:
      • medical:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • dental:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • vision:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • life:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • add:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • std:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • ltd:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • accident:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • critical_illness:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • cancer:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • hospital_indemnity:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan

Create Renewal Decisions Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
status* string Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted
group_id* uuid Unique identifier of the group in Noyo
renewal_date* date The start date for the new enrollment year when all coverage changes and decisions should become active
body* object
  • carriers*:
    • carrier_id*: Unique identifier of the carrier in Noyo
    • lines_of_coverage:
      • medical:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • dental:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • vision:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • life:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • add:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • std:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • ltd:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • accident:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • critical_illness:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • cancer:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • hospital_indemnity:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
issues* array
  • level*: The level or severity of the issue found. One of: error, warning
  • message*: Message describing the issue found and any steps to resolve
  • carrier_id: Unique identifier of the associated carrier in Noyo
  • line_of_coverage: Line of coverage related to the issue

Edit Renewal Decisions

Code Sample

curl -X PUT
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/renewal_decisions/4093a441-d4c8-4c8a-24d1-e7a132fb1bc2/d012e6ac-05dd-4cbe-8666-940af78c9e56

Body Parameter


{
    "renewal_date": "2022-01-01",
    "body": {
        "carriers": [
            {
                "carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
                "lines_of_coverage": {
                    "medical": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "818e52d4-6c34-4914-b716-a3047c85e468"
                            },
                            {
                                "plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2"
                            },
                            {
                                "name": "Select Plus PPO HDHP Bronze BRJJ /C38"
                            }
                        ]
                    },
                    "dental": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "name": "Dental Plus Plan"
                            }
                        ]
                    }
                }
            }
        ]
    }
}

Example Response

{
    "id": "b5f2b5f7-0336-45f7-baf1-7e11dfac50a6",
    "version": "23be0ba3-1183-4e8e-8e9d-644527414c6e",
    "created": 1557862286,
    "modified": 1557862286,
    "status": "submitted",
    "group_id": "2c4d5515-6bf8-4f8c-821a-9c56374198b2",
    "renewal_date": "2022-01-01",
    "body": {
        "carriers": [
            {
                "carrier_id": "bf81f0c4-3105-4240-b62b-aa6de3f607e4",
                "lines_of_coverage": {
                    "medical": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "818e52d4-6c34-4914-b716-a3047c85e468",
                                "name": "Select Plus PPO HDHP Gold BRJJ /C38"
                            },
                            {
                                "plan_id": "f9897240-87f8-4d9d-a68f-58bc445fe0b2",
                                "name": "Select Plus PPO HDHP Silver BRJJ /C38"
                            },
                            {
                                "plan_id": "19437852-3795-4cb4-939c-a86543eabee0",
                                "name": "Select Plus PPO HDHP Bronze BRJJ /C38"
                            }
                        ]
                    },
                    "dental": {
                        "open_enrollment_start_date": "2022-01-01",
                        "open_enrollment_end_date": "2022-01-31",
                        "plans": [
                            {
                                "plan_id": "44bc0f4a-0a94-11ec-9a03-0242ac130003",
                                "name": "Dental Plus Plan"
                            }
                        ]
                    }
                }
            }
        ]
    },
    "issues": []
}

Edit an existing renewal decision for a group.

Path Parameters

renewal_decision_id The unique identifier of the renewal decision you want to edit
version The unique identifier of the renewal decision version you want to edit

Request Body

renewal_date date The start date for the new enrollment year when all coverage changes and decisions should become active
body object
  • carriers*:
    • carrier_id*: Unique identifier of the carrier in Noyo
    • lines_of_coverage:
      • medical:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • dental:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • vision:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • life:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • add:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • std:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • ltd:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • accident:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • critical_illness:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • cancer:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • hospital_indemnity:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan

Edit Renewal Decisions Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
status* string Calculated status based on whether or not the carrier system matches the expected renewal decisions. One of: not_ready, ready, submitted
group_id* uuid Unique identifier of the group in Noyo
renewal_date* date The start date for the new enrollment year when all coverage changes and decisions should become active
body* object
  • carriers*:
    • carrier_id*: Unique identifier of the carrier in Noyo
    • lines_of_coverage:
      • medical:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • dental:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • vision:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • life:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • add:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • std:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • ltd:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • accident:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • critical_illness:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • cancer:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
      • hospital_indemnity:
        • open_enrollment_start_date: ISO-8601 date string for the start of the open enrollment period when member requests and changes can be processed
        • open_enrollment_end_date: ISO-8601 date string for the end of the open enrollment period when member requests and changes can be processed
        • plans:
          • plan_id: Unique ID of a group plan that exists in the Noyo system
          • name: Name of the group plan
issues* array
  • level*: The level or severity of the issue found. One of: error, warning
  • message*: Message describing the issue found and any steps to resolve
  • carrier_id: Unique identifier of the associated carrier in Noyo
  • line_of_coverage: Line of coverage related to the issue

Dropping Coverage

Use an empty object like the dental example below on a POST or a PUT to drop coverage

{
  "renewal_date": "2022-01-01",
  "body": {
    "carriers": [
      {
        "carrier_id": "4d4d815b-ae8f-430c-901f-1c9d5ee3f4f1",
        "lines_of_coverage": {
          "medical": {
            "open_enrollment_start_date": "2021-07-01",
            "open_enrollment_end_date": "2021-08-31",
            "plans": [
              {
                "name": "Select Plus PPO HDHP Bronze BRJJ / C38"
              }
            ]
          }
        }
      },
      {
        "carrier_id": "6026ccdd-14e0-44dd-a68f-86b08cc89cf4",
        "lines_of_coverage": {
          "dental": {}
        }
      }
    ]
  }
}

To confirm that coverage should be discontinued and no plans should be active for an upcoming renewal, you can pass an empty block for that carrier and line of coverage.

Also note that omitting a carrier from the request will mean that carrier is not evaluated for renewal readiness, and omitting a line of coverage for a carrier will mean that whether or not coverage is found would not impact the overall status or reported issues.

Based on this example request, we would evaluate renewal readiness for the group with the two provided carriers. We would expect one medical plan to be active at the first carrier and no dental coverage to be active at the second carrier, while the presence of any other lines of coverage at either carrier would be ignored.

Open Enrollment

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/open_enrollment

Body Parameter


{
    "coverages": [
        {
            "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
            "carrier_config": {},
            "signature_date": "2022-01-15",
            "lines_of_coverage": {
                "medical": {
                    "adding_coverage": [
                        {
                            "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                            "member_type": "dependent",
                            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                        }
                    ]
                }
            }
        }
    ]
}

Example Response

{
    "id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "request_type": "open_enrollment",
    "status": "processing",
    "transactions": [
        "579952dd-9a66-4587-a4f7-72a63bf9ec86"
    ],
    "body": {
        "coverages": [
            {
                "carrier_config": {},
                "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
                "lines_of_coverage": {
                    "medical": {
                        "adding_coverage": [
                            {
                                "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                                "member_type": "dependent",
                                "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                            }
                        ]
                    }
                },
                "signature_date": "2022-01-15"
            }
        ]
    }
}

The open enrollment member request is used to make changes to existing employees, dependents and coverages during the open enrollment period.

Path Parameters

employee_id The unique identifier of the employee related to the member request

The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:

Key Description
accident Accident
add Accidental Death & Dismemberment
cancer Cancer
critical_illness Critical Illness
dental Dental
hospital_indemnity Hospital Indemnity
life Life
ltd Long Term Disability
medical Medical
std Short Term Disability
vision Vision

Signature Date

Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.

signature_date string ISO-8601 date string for signature date

Coverage Actions

Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.

Adding Coverage

The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier along with the plan_id. The plan_id can be retrieved by selecting a valid plan from the group plans list.

Adding medical, dental, vision, accident, cancer or hospital_indemnity coverage

Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
prior_coverage object
  • 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, ltd and critical_illness coverage

Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
volumeˢ integer Elected volume for the type of coverage being selected
prior_coverage object
  • 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 / plan combination, given that the member already has coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or provide a new carrier_config to remain on the same plan but move the member into a new subgroup or benefit class.

Modifying medical, dental, vision, accident, cancer or hospital_indemnity coverage

Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member modifying coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo

Modifying life, add, std, ltd and critical_illness coverage

Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member modifying coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
volumeˢ integer Elected volume for the type of coverage being selected

Open Enrollment Transactions

One or more open enrollment transactions will created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).

Open Enrollment Member Transaction completed Result

Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.

New Hire Enrollment

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/72af10df-a8b3-46f1-a114-ac36d4b8a6ea/member_requests/new_hire

Body Parameter


{
    "coverages": [
        {
            "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
            "carrier_config": {},
            "signature_date": "2020-01-15",
            "lines_of_coverage": {
                "dental": {
                    "enrolling_members": [
                        {
                            "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                            "member_type": "employee",
                            "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                        },
                        {
                            "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                            "member_type": "dependent",
                            "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                        }
                    ]
                },
                "vision": {
                    "enrolling_members": [
                        {
                            "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                            "member_type": "employee",
                            "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                        },
                        {
                            "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                            "member_type": "dependent",
                            "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                        }
                    ]
                }
            }
        }
    ]
}

Example Response

{
    "id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
    "employee_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
    "request_type": "new_hire",
    "status": "processing",
    "transactions": [
        "a6e30204-87b2-4802-95a4-a156bd0f7435"
    ],
    "body": {
        "coverages": [
            {
                "carrier_config": {},
                "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
                "lines_of_coverage": {
                    "dental": {
                        "enrolling_members": [
                            {
                                "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                                "member_type": "employee",
                                "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                            },
                            {
                                "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                                "member_type": "dependent",
                                "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                            }
                        ]
                    },
                    "vision": {
                        "enrolling_members": [
                            {
                                "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                                "member_type": "employee",
                                "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                            },
                            {
                                "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                                "member_type": "dependent",
                                "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                            }
                        ]
                    }
                },
                "signature_date": "2020-01-15"
            }
        ]
    },
    "result": {}
}

The new hire member request is used to add an existing employee, and optionally their dependents to multiple coverages at multiple carriers.

Path Parameters

employee_id The unique identifier of the employee related to the member request

Creating Employees and Dependents

Prior to adding an employee and dependent(s) to coverage, you should ensure they have been added to the API via the create employee and create dependent endpoints. Note: The hire_date of the employee will be sent to the carrier and the beginning of the coverage will be computed by the carrier according to the waiting period for the group.

The Coverages Object

The coverages array contains one entry for each carrier with which you would like to enroll or waive coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:

Key Description
accident Accident
add Accidental Death & Dismemberment
cancer Cancer
critical_illness Critical Illness
dental Dental
hospital_indemnity Hospital Indemnity
life Life
ltd Long Term Disability
medical Medical
std Short Term Disability
vision Vision

Signature Date

Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.

signature_date string ISO-8601 date string for signature date

Enrolling Members

You must provide an enrolling_members entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.

Enrolling in medical, dental, vision, accident, cancer or hospital_indemnity

Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo

Enrolling in life, add, std, ltd or critical_illness

Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
volumeˢ integer Elected volume for the type of coverage being selected

Waiving Members

You can provide a waiving_members entry for each employee or dependent that is waiving coverage with the carrier along with the reason for waiving the coverage. This information will be communicated with the carrier where applicable. If you did not capture this information and only have the enrolling_members information the API request will still succeed.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member waiving coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
reason* string Reason the member is waiving coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal

New Hire Member Request Result

Sample Request Result

{
    "dental": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }],
    "vision": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }]
}

Upon the successful completion of all the transactions in the new hire member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:

member_id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member for the member enrollment result. One of: dependent, employee
individual_enrollment_id* uuid Unique identifier of the individual enrollment in Noyo created by the member request

New Hire Transactions

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_transactions/a6e30204-87b2-4802-95a4-a156bd0f7435

Example Response

{
    "id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
    "member_request_id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
    "employee_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
    "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
    "lines_of_coverage": [
        "dental",
        "vision"
    ],
    "status": "processing",
    "type": "carrier_new_hire",
    "body": {
        "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
        "lines_of_coverage": {
            "dental": {
                "enrolling_members": [{
                    "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                    "member_type": "employee",
                    "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                }, {
                    "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                    "member_type": "dependent",
                    "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                }]
            },
            "vision": {
                "enrolling_members": [{
                    "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                    "member_type": "employee",
                    "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                }, {
                    "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                    "member_type": "dependent",
                    "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                }]
            }
        }
    }
}

A new hire transaction is created for each entry in the coverages array (i.e. one transaction per carrier) with a type of carrier_new_hire.

New Hire Member Transaction completed Result

Upon the successful completion of the transaction, the status of the member transaction will be updated to completed and the result of the member transaction will be in the same format as the member request result

Qualifying Life Event

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/qualifying_life_event

Body Parameter


{
    "event": {
        "event_type": "newborn",
        "event_date": "2020-01-01"
    },
    "coverages": [
        {
            "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
            "carrier_config": {},
            "signature_date": "2020-01-15",
            "lines_of_coverage": {
                "medical": {
                    "adding_coverage": [
                        {
                            "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                            "member_type": "dependent",
                            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                        }
                    ]
                }
            }
        }
    ]
}

Example Response

{
    "id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "request_type": "qualifying_life_event",
    "status": "processing",
    "transactions": [
        "579952dd-9a66-4587-a4f7-72a63bf9ec86"
    ],
    "body": {
        "coverages": [
            {
                "carrier_config": {},
                "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
                "lines_of_coverage": {
                    "medical": {
                        "adding_coverage": [
                            {
                                "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                                "member_type": "dependent",
                                "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                            }
                        ]
                    }
                },
                "signature_date": "2020-01-15"
            }
        ],
        "event": {
            "event_date": "2020-01-01",
            "event_type": "newborn"
        }
    }
}

The qualifying life event member request is used to make changes to existing employees, dependents and coverages due to a qualifying life event.

Path Parameters

employee_id The unique identifier of the employee related to the member request

The Event Object

Each Qualifying Life Event requires an event parameter in the body which provides information about the type of the event as well as the date of its occurence. The schema for the event must follow this structure:

event_type* string Qualifying life event type. One of: adoption, change_to_full_time, change_to_part_time, classifications_change, court_order, death, dependent_open_enrollment, divorce, foster_care, immigration_status_change, legal_guardian, lost_coverage, marriage, medicare, moved, newborn, offline_change, rate_changed, rehire, reinstatement
event_date* string ISO-8601 date string for qualifying life event date

Event Types Available

Value Description
adoption This applies in the event that a member is looking to either add or remove coverage as a result of an adoption.
change_to_full_time This is often tied to benefit class or time status changes.
change_to_part_time This is often tied to a reduction of hours or a benefit class change.
court_order This is also sometimes known as QMCSO (qualified medical child support orders).
death This is applicable to employee, child, or spouse deaths and can be passed when adding or removing coverage due to death. Sending this is useful clarification in survivorship scenarios.
dependent_open_enrollment This refers to a case in which the dependent is removing themselves from another member's coverage and going through their own open enrollment.
divorce This applies in the event that a member is looking to either add or remove coverage as a result of a divorce.
foster_care This refers to a member adding a foster child to coverage.
immigration_status_change This can refer to a case in which the spouse obtains a green card and is then added to member's coverage.
legal_guardian This is applicable when a member becomes a legal guardian for a child and adds the child to coverage.
lost_coverage This is a catch-all for when a member is losing coverage not due to any other QLEs mentioned above. This is applicable when adding someone to coverage due to lost coverage elsewhere and also when removing them from coverage.
marriage This applies in the event that a member is looking to either add or remove coverage as a result of a marriage.
medicare This is applicable when a member gains medicare coverage or when member loses medicare coverage.
moved In this scenario, an address change makes someone either eligible or ineligible for coverage.
newborn This applies in the event that a member is looking to either add or remove coverage as a result of the birth of a child.
offline_change A change made outside of conventional open enrollment or special enrollment periods.
rate_changed This refers to a specific case in which a rate changes after the employee elects coverage. Some benefits administration platforms allow the employee to reselect coverage if they are dissatisfied with the new rates in these cases.
rehire Noyo currently makes no distinction between rehire and reinstatement cases. This code is applicable in both cases.
reinstatement Coverage is being resumed after a gap.

The QLE Coverages Object

The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:

Key Description
accident Accident
add Accidental Death & Dismemberment
cancer Cancer
critical_illness Critical Illness
dental Dental
hospital_indemnity Hospital Indemnity
life Life
ltd Long Term Disability
medical Medical
std Short Term Disability
vision Vision

Signature Date

Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.

signature_date string ISO-8601 date string for signature date

Coverage Actions

Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.

Adding Coverage

The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.

Adding medical, dental, vision, accident, cancer or hospital_indemnity coverage

Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
prior_coverage object
  • 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, ltd or critical_illness coverage

Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
volumeˢ integer Elected volume for the type of coverage being selected
prior_coverage object
  • 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 / plan combination, given that the member already has coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or provide a new carrier_config to remain on the same plan but move the member into a new subgroup or benefit class.

Modifying medical, dental, vision, accident, cancer or hospital_indemnity coverage

Medical, dental, vision, accident, cancer and hospital_indemnity coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member modifying coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo

Modifying life, add, std, ltd and critical_illness coverage

Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member modifying coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
volumeˢ integer Elected volume for the type of coverage being selected

Qualifying Life Event Member Request Result

Sample Request Result

{
    "dental": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }],
    "vision": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }]
}

Upon the successful completion of all the transactions in the qualifying life event member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:

member_id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member for the member enrollment result. One of: dependent, employee
individual_enrollment_id* uuid Unique identifier of the individual enrollment in Noyo created by the member request

Qualifying Life Event Transactions

One or more qualifying life event transactions will created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).

Qualifying Life Event Member Transaction completed Result

Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.

Termination

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/6dc22bed-27fc-458c-b732-bdaf5b5a1031/member_requests/termination

Body Parameter


{
    "reason": "voluntary",
    "last_work_date": "2020-01-15",
    "signature_date": "2020-01-01"
}

Example Response

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "created": 1557512389,
    "modified": 1564440756,
    "employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
    "request_type": "termination",
    "status": "processing",
    "transactions": [
        "f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
    ],
    "body": {
        "employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
        "last_work_date": "2020-01-15",
        "reason": "voluntary",
        "signature_date": "2020-01-01"
    }
}

The termination member request is used to remove an employee and their dependents from coverage at all carriers. The last_work_date will be communicated to the carrier and the last_day_of_coverage will be determined by the carrier and included in the result.

Path Parameters

employee_id The unique identifier of the employee related to the member request

Body Parameters

The member request for termination is straightforward and requires the following parameters in the body:

reason* string Reason for employee termination of coverage. One of: involuntary, job-eliminated, leave-of-absence, loss-of-eligibility, member-deceased, military-leave, voluntary
last_work_date* string ISO-8601 date string for last day of work of the terminated employee
signature_date string ISO-8601 date string for signature date

Signature Date

Within the termination request body you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system to the carrier as the signature_date.

Termination Transactions

A termination transaction is created for each carrier that the employee and dependents have coverage with a type of carrier_termination. A transaction is also created with the type noyo_termination. The noyo_termination transaction will complete on the last_work_date and will update the Employee object to be marked as terminated along with information about the last day of employment.

Carrier Termination Result

The result of the carrier_termination member transaction will include the last day that the members are covered at the carrier. The individual enrollments for the carrier will also be updated with a new status of terminated.

Sample Transaction Result

{
    "last_day_of_coverage": "2018-02-01"
}

Demographic Change

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/demographic

Body Parameter


{
    "change_date": "2020-01-15",
    "signature_date": "2020-01-15",
    "member_changes": [
        {
            "member": {
                "id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
                "type": "employee"
            },
            "name_change": {
                "first_name": "David",
                "last_name": "Williamson"
            },
            "contact_change": {
                "home_phone": "+15555551212",
                "work_phone": "+15555551212",
                "email_address": "david.williamson@example.com",
                "email_address_type": "home"
            },
            "salary_change": {
                "amount": 55000,
                "unit": "annual",
                "type": "salary"
            }
        }
    ]
}

Example Response

{
    "id": "db6f362a-9f90-49b2-a73d-830cd2726537",
    "created": 1557512389,
    "modified": 1564440756,
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "request_type": "demographic",
    "status": "processing",
    "transactions": [
        "b56bfe70-2632-49e9-b269-1eaa36ed7fd6"
    ],
    "body": {
        "change_date": "2020-01-15",
        "member_changes": [
            {
                "contact_change": {
                    "email_address": "david.williamson@example.com",
                    "email_address_type": "home",
                    "home_phone": "+15555551212",
                    "work_phone": "+15555551212"
                },
                "member": {
                    "id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
                    "member_type": "employee"
                },
                "name_change": {
                    "first_name": "David",
                    "last_name": "Williamson"
                },
                "salary_change": {
                    "amount": 55000,
                    "type": "salary",
                    "unit": "annual"
                }
            }
        ],
        "signature_date": "2020-01-15"
    }
}

The demographic change member request is used to update information such as name, address, and salary for one or many members. The updates will be carried out for each carrier that has a record of each member.

Path Parameters

employee_id The unique identifier of the employee related to the member request

Demographic Change Member Request Body

change_date string ISO-8601 date string for effective date of demographic change
signature_date string ISO-8601 date string for signature date
member_changes* array
  • 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, U, X
  • 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
  • classifications_change: Details about a demographic classifications change request

Demographic Change Member Request Result

Sample Request Result

[{
    "id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
    "type" "employee",
    "version": "cf78e9b2-6213-448b-a0b9-04a254a84872"
}]

Upon the successful completion of all the transactions in the demographic change member request, the status of the member request will be updated to completed and the result of the member request will be an object containing an array of updated members. The employee and dependent objects in the Noyo API will be updated only when all transactions have completed.

COBRA Enrollment

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/72af10df-a8b3-46f1-a114-ac36d4b8a6ea/member_requests/cobra_enrollment

Body Parameter


{
    "termination_info": {
        "reason": "voluntary",
        "last_work_date": "2020-01-01"
    },
    "coverages": [
        {
            "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
            "carrier_config": {},
            "signature_date": "2020-01-15",
            "lines_of_coverage": {
                "dental": {
                    "enrolling_members": [
                        {
                            "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                            "member_type": "employee",
                            "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                        },
                        {
                            "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                            "member_type": "dependent",
                            "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                        }
                    ]
                },
                "vision": {
                    "enrolling_members": [
                        {
                            "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                            "member_type": "employee",
                            "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                        },
                        {
                            "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                            "member_type": "dependent",
                            "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                        }
                    ]
                }
            }
        }
    ]
}

Example Response

{
    "id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
    "created": 1557512389,
    "modified": 1564440756,
    "employee_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
    "request_type": "cobra_enrollment",
    "status": "processing",
    "transactions": [
        "a6e30204-87b2-4802-95a4-a156bd0f7435"
    ],
    "body": {
        "coverages": [
            {
                "carrier_config": {},
                "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
                "lines_of_coverage": {
                    "dental": {
                        "enrolling_members": [
                            {
                                "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                                "member_type": "employee",
                                "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                            },
                            {
                                "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                                "member_type": "dependent",
                                "plan_id": "ff033377-59e2-40df-8206-8cec3a725411"
                            }
                        ]
                    },
                    "vision": {
                        "enrolling_members": [
                            {
                                "id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
                                "member_type": "employee",
                                "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                            },
                            {
                                "id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
                                "member_type": "dependent",
                                "plan_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
                            }
                        ]
                    }
                },
                "signature_date": "2020-01-15"
            }
        ],
        "termination_info": {
            "last_work_date": "2020-01-01",
            "reason": "voluntary"
        }
    },
    "result": {}
}

The COBRA enrollment member request is used to add an existing employee, and optionally their dependents to multiple coverages at multiple carriers. This is for a continuation of benefits situation, when main line coverage either has already been terminated, or will be in conjunction with this member request.

Path Parameters

employee_id The unique identifier of the employee related to the member request

Termination Info

The termination_info block contains information about the termination of the employee prior to COBRA enrollment. If you have already sent a Termination Member Request for the employee the data from that request will be used. If you have not sent a Termination Member Request the data from this request will be used to terminate the member at the carrier.

reason* string Reason for employee termination of coverage. One of: involuntary, job-eliminated, leave-of-absence, loss-of-eligibility, member-deceased, military-leave, voluntary
last_work_date* string ISO-8601 date string for last day of work of the terminated employee

The Coverages Object

The coverages array contains one entry for each carrier with which you would like to enroll or waive coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys:

Key Description
accident Accident
add Accidental Death & Dismemberment
cancer Cancer
critical_illness Critical Illness
dental Dental
hospital_indemnity Hospital Indemnity
life Life
ltd Long Term Disability
medical Medical
std Short Term Disability
vision Vision

Signature Date

Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.

signature_date string ISO-8601 date string for signature date

Enrolling Members

You must provide an enrolling_members entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.

Enrolling in medical, dental, vision, accident, cancer or hospital_indemnity

Medical, dental, vision, accident, cancer and hospital indemnity coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo

Enrolling in life, add, std, ltd or critical_illness

Life, AD&D, STD, LTD and critical illness coverage also optionally accept volume parameter in dollars (e.g. $50,000 should be sent as 50000).

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
volumeˢ integer Elected volume for the type of coverage being selected

Waiving Members

You can provide a waiving_members entry for each employee or dependent that is waiving coverage with the carrier along with the reason for waiving the coverage. This information will be communicated with the carrier where applicable. If you did not capture this information and only have the enrolling_members information the API request will still succeed.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member waiving coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
reason* string Reason the member is waiving coverage. One of: medi-cal, medicaid, no-coverage, other-cobra, other-employee-group, other-ind-off-exchange, other-ind-on-exchange, other-medicare, other-parent-group, other-spouse-group, retiree-coverage, tricare-coverage, va-coverage, voluntary-withdrawal

Sample Request Result

{
    "dental": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }],
    "vision": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }]
}

Upon the successful completion of all the transactions in the member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:

member_id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member for the member enrollment result. One of: dependent, employee
individual_enrollment_id* uuid Unique identifier of the individual enrollment in Noyo created by the member request

COBRA Open Enrollment

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/cobra_open_enrollment

Body Parameter


{
    "coverages": [
        {
            "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
            "carrier_config": {},
            "signature_date": "2021-01-15",
            "lines_of_coverage": {
                "medical": {
                    "adding_coverage": [
                        {
                            "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                            "member_type": "dependent",
                            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                        }
                    ]
                }
            }
        }
    ]
}

Example Response

{
    "id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
    "created": 1557512389,
    "modified": 1564440756,
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "request_type": "cobra_open_enrollment",
    "status": "processing",
    "transactions": [
        "579952dd-9a66-4587-a4f7-72a63bf9ec86"
    ],
    "body": {
        "coverages": [
            {
                "carrier_config": {},
                "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
                "lines_of_coverage": {
                    "medical": {
                        "adding_coverage": [
                            {
                                "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                                "member_type": "dependent",
                                "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                            }
                        ]
                    }
                },
                "signature_date": "2021-01-15"
            }
        ]
    }
}

The COBRA open enrollment member request is used to make changes to employees, dependents and COBRA coverages during the open enrollment period.

Path Parameters

employee_id The unique identifier of the employee related to the member request

The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. The lines_of_coverage object allows the following keys for COBRA open enrollment:

Key Description
dental Dental
medical Medical
vision Vision

Signature Date

Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.

signature_date string ISO-8601 date string for signature date

Coverage Actions

Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.

Adding Coverage

The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier along with the COBRA eligible plan_id. The plan_id can be retrieved by selecting a valid plan from the group plans list.

Adding medical, dental, or vision coverage

Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
prior_coverage object
  • 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 COBRA enrolled member / plan combination, given that the member already has COBRA coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or pass the same set of plans to remain on COBRA coverage with no changes.

Modifying medical, dental, or vision coverage

Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member modifying coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo

COBRA Open Enrollment Transactions

One or more COBRA open enrollment transactions will created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).

COBRA Open Enrollment Member Transaction completed Result

Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.

COBRA Qualifying Life Event

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests/cobra_qualifying_life_event

Body Parameter


{
    "event": {
        "event_date": "2021-01-01",
        "event_type": "newborn"
    },
    "coverages": [
        {
            "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
            "carrier_config": {},
            "signature_date": "2021-01-15",
            "lines_of_coverage": {
                "medical": {
                    "adding_coverage": [
                        {
                            "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                            "member_type": "dependent",
                            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                        }
                    ]
                }
            }
        }
    ]
}

Example Response

{
    "id": "f4517b87-275a-42e1-85e5-47ea6ab5312b",
    "created": 1557512389,
    "modified": 1564440756,
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "request_type": "cobra_qualifying_life_event",
    "status": "processing",
    "transactions": [
        "579952dd-9a66-4587-a4f7-72a63bf9ec86"
    ],
    "body": {
        "coverages": [
            {
                "carrier_config": {},
                "carrier_id": "9a0a7437-4097-4251-9e71-85384c0eb1c9",
                "lines_of_coverage": {
                    "medical": {
                        "adding_coverage": [
                            {
                                "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
                                "member_type": "dependent",
                                "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a"
                            }
                        ]
                    }
                },
                "signature_date": "2021-01-15"
            }
        ],
        "event": {
            "event_date": "2021-01-01",
            "event_type": "newborn"
        }
    }
}

The COBRA qualifying life event member request is used to make changes to employees, dependents and COBRA coverages due to a qualifying life event.

Path Parameters

employee_id The unique identifier of the employee related to the member request

The Event Object

Each COBRA Qualifying Life Event requires an event parameter in the body which provides information about the type of the event as well as the date of its occurrence. The schema for the event must follow this structure:

event_type* string Qualifying life event type. One of: adoption, change_to_full_time, change_to_part_time, classifications_change, court_order, death, dependent_open_enrollment, divorce, foster_care, immigration_status_change, legal_guardian, lost_coverage, marriage, medicare, moved, newborn, offline_change, rate_changed, rehire, reinstatement, terminate_cobra
event_date* string ISO-8601 date string for qualifying life event date

The COBRA QLE Coverages Object

The coverages array contains one entry for each carrier with which you would like to make changes to coverage. The carrier_id along with the schema of the carrier_config object will be provided by the Noyo team. You can reference the group carrier configuration resource to get additional carrier-specific data. For COBRA QLE requests, the lines_of_coverage object allows the following keys:

Key Description
dental Dental
medical Medical
vision Vision

Signature Date

Within each entry in the coverages array you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system as the signature_date to the carrier.

signature_date string ISO-8601 date string for signature date

Coverage Actions

Within each object inside of lines_of_coverage you may provide three different actions: adding_coverage, removing_coverage, and modifying_coverage. More information about each of these is below.

Adding Coverage

The adding_coverage action is used to add new coverage for a member with a carrier. You must provide an adding_coverage entry for each employee or dependent that is enrolling in coverage with the carrier. The plan_id field is optional in each action. If you do not specify a plan_id, we will try to automatically select an available plan for the member based on the current group plans. When the group has more than one eligible plan for a member, you will need to specify the COBRA eligible plan_id in the request. Plan IDs can be retrieved using the group plans endpoint.

Adding medical, dental, or vision coverage

Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member adding coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo
prior_coverage object
  • 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 COBRA enrolled member / plan combination, given that the member already has COBRA coverage on that plan with the carrier. For example, you can use the modifying_coverage action to change the volume of coverage for a member's existing life or disability plan, or pass the same set of plans to remain on COBRA coverage with no changes.

Modifying medical, dental, or vision coverage

Medical, dental, and vision coverage do not require any information beyond the member information and the selected plan.

id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member modifying coverage. One of: dependent, employee
plan_id uuid Unique identifier of the group plan in Noyo

COBRA Qualifying Life Event Member Request Result

Sample Request Result

{
    "dental": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "ff033377-59e2-40df-8206-8cec3a725411"
    }],
    "vision": [{
        "member_id": "72af10df-a8b3-46f1-a114-ac36d4b8a6ea",
        "member_type": "employee",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }, {
        "member_id": "165d4537-be5f-4744-8a97-a5b10fcb75b1",
        "member_type": "dependent",
        "individual_enrollment_id": "08f9e430-9686-4b07-9e2c-6b26b8133dc3"
    }]
}

Upon the successful completion of all the transactions in the COBRA qualifying life event member request, the status of the member request will be updated to completed and the result of the member request will be an object with a key for each coverage (e.g. dental, vision) and an array with the following:

member_id* uuid Unique identifier of the employee or dependent in Noyo
member_type* string Type of member for the member enrollment result. One of: dependent, employee
individual_enrollment_id* uuid Unique identifier of the individual enrollment in Noyo created by the member request

COBRA Qualifying Life Event Transactions

One or more COBRA qualifying life event transactions will be created based on the requested changes in the coverages array. For some carriers, there may be a single transaction including all of the requested changes, while other carriers may require separate transactions for each action type (i.e. one transaction per action per carrier).

COBRA Qualifying Life Event Member Transaction completed Result

Upon the successful completion of the transaction, the status of the member transaction will be updated and the result of the member transaction will be in the same format as the member request result.

COBRA Termination

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/6dc22bed-27fc-458c-b732-bdaf5b5a1031/member_requests/cobra_termination

Body Parameter


{
    "reason": "voluntary",
    "cobra_termination_date": "2021-01-15",
    "signature_date": "2021-01-01"
}

Example Response

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "created": 1557512389,
    "modified": 1564440756,
    "employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
    "request_type": "cobra_termination",
    "status": "processing",
    "transactions": [
        "f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
    ],
    "body": {
        "cobra_termination_date": "2021-01-15",
        "reason": "voluntary",
        "signature_date": "2021-01-01"
    }
}

The COBRA termination member request is used to remove an employee and their dependents from COBRA coverage at all carriers. The cobra_termination_date is the date on which the COBRA coverage should be terminated.

Path Parameters

employee_id The unique identifier of the employee related to the member request

Body Parameters

The member request for COBRA termination is straightforward and requires the following parameters in the body:

reason* string Reason the member has removed or canceled COBRA coverage. One of: expiration, involuntary, medicare-entitlement, new-enrollment, non-payment, voluntary
cobra_termination_date* string The COBRA Termination event date.
signature_date string ISO-8601 date string for signature date

Signature Date

Within the COBRA termination request body you can optionally specify a signature_date. The signature_date is the date when the employee or employer signed for the change to be made. If a signature_date is not provided we will communicate the date the member request was received by the Noyo system to the carrier as the signature_date.

COBRA Termination Transactions

A COBRA termination transaction is created for each carrier that the employee and dependents have coverage with a type of carrier_cobra_termination.

Carrier COBRA Termination Result

The result of the carrier_cobra_termination member transaction will include the last day that the members are covered at the carrier. The individual enrollments for the carrier will also be updated with a new status of terminated.

Sample Transaction Result

{
    "last_day_of_coverage": "2018-02-01"
}

Member Premiums

Returns a premium amount billed to members for coverage with a carrier.

Premium Breakdown

Callers can query the API by employee ID to retrieve a list of member premiums associated with an employee and their family unit. The size of the response list will depend on the granularity of data made available by the carrier.

For example, if an employee is enrolled in dental and vision coverage and we know the exact cost split between each line of coverage, the response list would contain two member premium records, one with the dental amount and a single billed_members entry for the employee + dental plan, and one with the vision amount and a single billed_members entry for the employee + vision plan.

On the other hand, if we only know the total combined cost for both coverages, the response list would contain one member premium record with the total amount and two billed_members entries, one for the employee + dental plan and one for the employee + vision plan.

By Employee

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/premiums

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 2
    },
    "response": [
        {
            "carrier_id": "e2c76400-b505-432a-a1c1-c777bcec4648",
            "amount": "50.00",
            "period": {
                "amount": 1,
                "unit": "month"
            },
            "premium_type": "employer_amount",
            "effective_start_date": "2020-01-01",
            "effective_end_date": "2020-12-31",
            "billed_members": [
                {
                    "member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
                    "member_type": "employee",
                    "line_of_coverage": "dental",
                    "plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
                },
                {
                    "member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
                    "member_type": "employee",
                    "line_of_coverage": "vision",
                    "plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
                },
                {
                    "member_id": "67309c4b-12f5-4bb0-92ce-a45639af9055",
                    "member_type": "dependent",
                    "line_of_coverage": "dental",
                    "plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
                },
                {
                    "member_id": "8f5aaf65-c4e6-4909-9ebf-58b320645df2",
                    "member_type": "dependent",
                    "line_of_coverage": "vision",
                    "plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
                }
            ],
            "created": 1599184829,
            "modified": 1599292817
        },
        {
            "carrier_id": "e2c76400-b505-432a-a1c1-c777bcec4648",
            "amount": "50.00",
            "period": {
                "amount": 1,
                "unit": "month"
            },
            "premium_type": "employee_amount",
            "effective_start_date": "2020-01-01",
            "effective_end_date": "2020-12-31",
            "billed_members": [
                {
                    "member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
                    "member_type": "employee",
                    "line_of_coverage": "dental",
                    "plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
                },
                {
                    "member_id": "4638b93f-b20a-4922-82b1-0f406891e2e3",
                    "member_type": "employee",
                    "line_of_coverage": "vision",
                    "plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
                },
                {
                    "member_id": "67309c4b-12f5-4bb0-92ce-a45639af9055",
                    "member_type": "dependent",
                    "line_of_coverage": "dental",
                    "plan_id": "8609ee91-772a-4047-8e2b-a79883cf05ea"
                },
                {
                    "member_id": "8f5aaf65-c4e6-4909-9ebf-58b320645df2",
                    "member_type": "dependent",
                    "line_of_coverage": "vision",
                    "plan_id": "e1793d34-700b-4c14-9425-d0f4f426d4d0"
                }
            ],
            "created": 1599184829,
            "modified": 1599292817
        }
    ]
}

Returns list of Member Premium information for an employee and dependents

Path Parameters

employee_id Unique ID of the employee in Noyo

Query Parameters

effective_date The relative date on which to view the state of the records. Defaults to today

Member Premium List

meta* object
  • 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 record in Noyo
  • version*: Current version of the record
  • carrier_id*: Unique ID of the carrier in Noyo
  • amount*: Total amount of the premium in USD
  • period*:
    • amount*: Length of premium period
    • unit*: Unit frequency of premium period. One of: annual, day, month, semi-monthly, week
  • premium_type*: Premium type, either the total premium, or just the employer-paid or employee-paid portion. One of: employee_amount, employer_amount, total_amount
  • effective_start_date*: ISO-8601 date string for the effective start date of the premium
  • effective_end_date: ISO-8601 date string for the effective end date of the premium
  • billed_members*:
    • member_id*: Unique ID of the billed member in Noyo
    • member_type*: Type of member for the billed premium. One of: dependent, employee
    • line_of_coverage*: Line of coverage for the billed group plan. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision
    • plan_id*: Unique identifier of the billed group plan in Noyo
  • created*: The date the record was created
  • modified*: The date the record was last updated

Verified Member Transactions

Often member transactions are sent in advance and will become effective at a date in the future (e.g, a new_hire member request with a hire_date of today, but the coverage does not start until the first of next month). Noyo works with carriers to verify that transactions have taken effect as expected and will mark the member transaction as verified when applicable. The verified field is the Unix time at which the member transaction was verified. You can expect the following timelines for verification at most carriers:

Transaction Type Timeline
New Hire On or shortly after the effective_start_date of the created individual enrollments
Termination On or shortly after the last_day_of_coverage
Qualifying Life Event On or shortly after the effective date of coverage changes
Open Enrollment On or shortly after the effective date of coverage changes
Demographic Change Immediately after completion of the member transaction

Member transactions and requests in the completed status require no additional attention or action from you. Think of verified transactions as ones where we were able to do a successful double check that everything went as we expected.

Note: There may be some cases where the carrier does not support verification. If the carrier supports verification and the member transaction does not verify in a timely manner we will notify you.

Getting Member Requests

Get Single Member Request

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_requests/dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1

Example Response

{
    "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
    "created": 1557512389,
    "completed": 1557565200,
    "modified": 1557565200,
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "request_type": "termination",
    "status": "processing",
    "transactions": [
        "f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
    ],
    "body": {
        "employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
        "last_work_date": "2018-01-15",
        "reason": "voluntary"
    }
}

Returns the latest version of a single member request based on the ID provided.

Path Parameters

request_id The unique identifier of the member request you would like to view

Get Single Member Request Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
completed timestamp Timestamp indicating when a member request was marked as completed
modified* timestamp The date the record was last updated
employee_id* uuid Unique identifier of the employee in Noyo
request_type* string Transaction type for the member request. One of: cobra_enrollment, cobra_open_enrollment, cobra_qualifying_life_event, cobra_termination, demographic, enrollment_snapshot, new_hire, open_enrollment, qualifying_life_event, termination
status* string Status of the member request. One of: canceled, completed, failed, processing
transactions array List of unique identifiers of all associated member transactions in Noyo
body* object Data required to execute a member request, varies depending on the request type
result* object Result from executing the member request, varies depending on the request type

For more information about the body and result fields check out the request-specific documentation

Get Member Requests for Employee

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/member_requests

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 2
    },
    "response": [
        {
            "id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
            "created": 1557512389,
            "completed": 1557565200,
            "modified": 1557565200,
            "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "request_type": "new_hire",
            "status": "processing",
            "transactions": [
                "a6e30204-87b2-4802-95a4-a156bd0f7435"
            ],
            "body": {
                "coverages": [
                    {
                        "carrier_config": {
                            "bill_group": "1000001",
                            "member_group": "99999"
                        },
                        "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
                        "lines_of_coverage": {
                            "dental": {
                                "waiving_members": [
                                    {
                                        "id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
                                        "member_type": "employee",
                                        "reason": "other-spouse-group"
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        },
        {
            "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
            "created": 1557512394,
            "completed": 1557565200,
            "modified": 1557565200,
            "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "request_type": "termination",
            "status": "processing",
            "transactions": [
                "f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
            ],
            "body": {
                "employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
                "last_work_date": "2018-01-15",
                "reason": "voluntary"
            }
        }
    ]
}

Returns a list of all member requests for a given employee. Each member request may have one or more associated member transactions.

Path Parameters

employee_id The unique identifier of the employee for which you would like to view member requests

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get All Member Requests

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_requests

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 2
    },
    "response": [
        {
            "id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
            "created": 1557512389,
            "completed": 1557565200,
            "modified": 1557565200,
            "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "request_type": "new_hire",
            "status": "processing",
            "transactions": [
                "a6e30204-87b2-4802-95a4-a156bd0f7435"
            ],
            "body": {
                "coverages": [
                    {
                        "carrier_config": {
                            "bill_group": "1000001",
                            "member_group": "99999"
                        },
                        "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
                        "lines_of_coverage": {
                            "dental": {
                                "waiving_members": [
                                    {
                                        "id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
                                        "member_type": "employee",
                                        "reason": "other-spouse-group"
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        },
        {
            "id": "dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1",
            "created": 1557512389,
            "completed": 1557565200,
            "modified": 1557565200,
            "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "request_type": "termination",
            "status": "processing",
            "transactions": [
                "f4ecdaa5-e019-4a24-98c7-2caee9a58ccd"
            ],
            "body": {
                "employee_id": "6dc22bed-27fc-458c-b732-bdaf5b5a1031",
                "last_work_date": "2018-01-15",
                "reason": "voluntary"
            }
        }
    ]
}

Returns a list of all member requests for a given organization. Each member request may have one or more associated member transactions.

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
employee_id Unique identifier of the employee in Noyo for which you would like to filter
status The member request status for which you would like to filter
request_type The member request type for which you would like to filter

Get All Member Requests Response

meta* object
  • 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 record in Noyo
  • version*: Current version of the record
  • created*: The date the record was created
  • completed: Timestamp indicating when a member request was marked as completed
  • 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: cobra_enrollment, cobra_open_enrollment, cobra_qualifying_life_event, cobra_termination, demographic, enrollment_snapshot, new_hire, open_enrollment, qualifying_life_event, termination
  • status*: Status of the member request. One of: canceled, 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.noyo.com/api/v1/member_requests?status=processing&request_type=new_hire

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "4f57e463-f4d5-4255-83d4-806b0cabaac5",
            "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "request_type": "new_hire",
            "status": "processing",
            "transactions": [
                "a6e30204-87b2-4802-95a4-a156bd0f7435"
            ],
            "body": {
                "coverages": [
                    {
                        "carrier_config": {
                            "bill_group": "1000001",
                            "member_group": "99999"
                        },
                        "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
                        "lines_of_coverage": {
                            "dental": {
                                "waiving_members": [
                                    {
                                        "id": "f471a562-fa8f-41c9-93fd-12b372e16c72",
                                        "member_type": "employee",
                                        "reason": "other-spouse-group"
                                    }
                                ]
                            }
                        }
                    }
                ]
            }
        }
    ]
}

For cases where you would like to filter the Member Requests for you organization, you can do so by passing in one or more of the filters below into the query string.

employee_id uuid Unique identifier of the employee in Noyo to be filtered on
group_id uuid Unique identifier of the group in Noyo to be filtered on
status string Status of the member request to be filtered on. One of: canceled, completed, failed, processing
request_type string Member request type to be filtered on. One of: cobra_enrollment, cobra_open_enrollment, cobra_qualifying_life_event, cobra_termination, demographic, enrollment_snapshot, new_hire, open_enrollment, qualifying_life_event, termination

Getting Member Transactions

Get Single Member Transaction

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_transactions/a6e30204-87b2-4802-95a4-a156bd0f7435

Example Response

{
    "id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
    "created": 1557512389,
    "modified": 1564440756,
    "member_request_id": "bba6ea27-4004-4a52-a3d9-f986ace0d3da",
    "employee_id": "25434576-e85d-481b-a825-962fd575046f",
    "carrier_id": "478e066e-9696-490e-b60f-47f40c96dc7c",
    "lines_of_coverage": [
        "medical",
        "dental",
        "vision"
    ],
    "status": "processing",
    "body": {
        "coverages": [
            {
                "carrier_config": {
                    "bill_group": "1000001",
                    "member_group": "99999"
                },
                "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
                "lines_of_coverage": {
                    "dental": {
                        "enrolling_members": [
                            {
                                "id": "25434576-e85d-481b-a825-962fd575046f",
                                "member_type": "employee",
                                "plan_id": "2e6a04b6-21f3-40d7-a9e2-735196cc451b"
                            }
                        ],
                        "waiving_members": []
                    },
                    "medical": {
                        "enrolling_members": [
                            {
                                "id": "25434576-e85d-481b-a825-962fd575046f",
                                "member_type": "employee",
                                "plan_id": "1873df52-c9e9-4e3a-995c-f47f32d0bd62"
                            }
                        ],
                        "waiving_members": []
                    },
                    "vision": {
                        "enrolling_members": [
                            {
                                "id": "25434576-e85d-481b-a825-962fd575046f",
                                "member_type": "employee",
                                "plan_id": "9cb64800-022e-40af-ab80-8d945e430592"
                            }
                        ],
                        "waiving_members": []
                    }
                }
            }
        ]
    }
}

Returns the latest version of a single member transaction based on the ID provided.

Path Parameters

transaction_id The unique identifier of the member transaction you would like to view

Get Single Member Transaction Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
member_request_id* uuid Unique identifier of the member request in the Noyo system
employee_id* uuid Unique identifier of the associated employee in the Noyo system
carrier_id uuid Unique identifier of the carrier in the Noyo system
lines_of_coverage* array List of lines of coverage for the member transaction. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision
transaction_type* string Transaction type of the member transaction. One of: carrier_cobra_enrollment, carrier_cobra_open_enrollment, carrier_cobra_qualifying_life_event, carrier_cobra_termination, carrier_demographic, carrier_demographic_full, carrier_enrollment_snapshot_new_hire, carrier_new_hire, carrier_open_enrollment_adding, carrier_open_enrollment_full, carrier_open_enrollment_modifying, carrier_open_enrollment_removing, carrier_qualifying_life_event_adding, carrier_qualifying_life_event_full, carrier_qualifying_life_event_modifying, carrier_qualifying_life_event_removing, carrier_termination, noyo_termination
status* string Status of the member transaction. One of: canceled, completed, failed, processing
verified timestamp The date the member transaction was verified
body* object Body of the member transaction
result* object Result of the member transaction

For more information about the body and result fields check out the request-specific documentation

Get Member Transaction Status Details

Status Details are the processing history of a member transaction. This endpoint will return a list of all status details for a given transaction, as well as the event_created timestamp signifying when the transaction entered each status.

The possible values for the status_detail field are detailed below.

Status Detail Description
noyo_accepted Noyo confirms we have successfully received your transaction request and will begin processing.
carrier_accepted Noyo confirms the carrier has successfully received the transaction we’ve sent on your behalf.
carrier_processing The transaction is currently being processed at the carrier.
carrier_completed The carrier has confirmed the transaction was successfully fulfilled. Noyo will now have the changes from the carrier reflected in the dashboard and via API.
noyo_verified Noyo has completed round-trip confirmation for the member transaction. This occurs on the date that all changes from the transaction are effective.

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_transactions/136e34f9-1eb5-4b31-af53-b3a37ef225ba/status_details

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 3
    },
    "response": [
        {
            "status_detail": "noyo_accepted",
            "event_created": 1673510745
        },
        {
            "status_detail": "carrier_accepted",
            "event_created": 1673510857
        },
        {
            "status_detail": "carrier_processing",
            "event_created": 1673510869
        }
    ]
}

Returns a list of all status details for a given transaction.

Path Parameters

transaction_id The unique identifier of the member transaction

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Member Transaction Status Details Response

This endpoint will return only the most recent status for a given transaction, with the event_created timestamp of when the transaction transitioned into this state.

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
  • status_detail*: Type of Status detail. One of: carrier_accepted, carrier_completed, carrier_processing, noyo_accepted, noyo_verified
  • event_created*: Timestamp indicating when the status detail was created

Get Member Transaction Latest Status Detail

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_transactions/136e34f9-1eb5-4b31-af53-b3a37ef225ba/status_details/latest

Example Response

{
    "status_detail": "carrier_accepted",
    "event_created": 1673510869
}

Returns the latest status detail for a given transaction.

Path Parameters

transaction_id The unique identifier of the member transaction

Get Member Transaction Latest Status Detail Response

status_detail* string Type of Status detail. One of: carrier_accepted, carrier_completed, carrier_processing, noyo_accepted, noyo_verified
event_created* timestamp Timestamp indicating when the status detail was created

Get Transactions for Request

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_requests/a6e30204-87b2-4802-95a4-a156bd0f7435/member_transactions

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
            "created": 1557512389,
            "modified": 1564440756,
            "member_request_id": "bba6ea27-4004-4a52-a3d9-f986ace0d3da",
            "employee_id": "25434576-e85d-481b-a825-962fd575046f",
            "carrier_id": "478e066e-9696-490e-b60f-47f40c96dc7c",
            "lines_of_coverage": [
                "medical",
                "dental",
                "vision"
            ],
            "status": "processing",
            "body": {
                "coverages": [
                    {
                        "carrier_config": {
                            "bill_group": "1000001",
                            "member_group": "99999"
                        },
                        "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
                        "lines_of_coverage": {
                            "dental": {
                                "enrolling_members": [
                                    {
                                        "id": "25434576-e85d-481b-a825-962fd575046f",
                                        "member_type": "employee",
                                        "plan_id": "2e6a04b6-21f3-40d7-a9e2-735196cc451b"
                                    }
                                ],
                                "waiving_members": []
                            },
                            "medical": {
                                "enrolling_members": [
                                    {
                                        "id": "25434576-e85d-481b-a825-962fd575046f",
                                        "member_type": "employee",
                                        "plan_id": "1873df52-c9e9-4e3a-995c-f47f32d0bd62"
                                    }
                                ],
                                "waiving_members": []
                            },
                            "vision": {
                                "enrolling_members": [
                                    {
                                        "id": "25434576-e85d-481b-a825-962fd575046f",
                                        "member_type": "employee",
                                        "plan_id": "9cb64800-022e-40af-ab80-8d945e430592"
                                    }
                                ],
                                "waiving_members": []
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Returns a list of all member transactions for a given member request.

Path Parameters

request_id The unique identifier of the member request for which you would like to view member transaction

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get All Member Transactions

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/member_transactions

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "a6e30204-87b2-4802-95a4-a156bd0f7435",
            "created": 1557512389,
            "modified": 1564440756,
            "member_request_id": "bba6ea27-4004-4a52-a3d9-f986ace0d3da",
            "employee_id": "25434576-e85d-481b-a825-962fd575046f",
            "carrier_id": "478e066e-9696-490e-b60f-47f40c96dc7c",
            "lines_of_coverage": [
                "medical",
                "dental",
                "vision"
            ],
            "status": "processing",
            "body": {
                "coverages": [
                    {
                        "carrier_config": {
                            "bill_group": "1000001",
                            "member_group": "99999"
                        },
                        "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
                        "lines_of_coverage": {
                            "dental": {
                                "enrolling_members": [
                                    {
                                        "id": "25434576-e85d-481b-a825-962fd575046f",
                                        "member_type": "employee",
                                        "plan_id": "2e6a04b6-21f3-40d7-a9e2-735196cc451b"
                                    }
                                ],
                                "waiving_members": []
                            },
                            "medical": {
                                "enrolling_members": [
                                    {
                                        "id": "25434576-e85d-481b-a825-962fd575046f",
                                        "member_type": "employee",
                                        "plan_id": "1873df52-c9e9-4e3a-995c-f47f32d0bd62"
                                    }
                                ],
                                "waiving_members": []
                            },
                            "vision": {
                                "enrolling_members": [
                                    {
                                        "id": "25434576-e85d-481b-a825-962fd575046f",
                                        "member_type": "employee",
                                        "plan_id": "9cb64800-022e-40af-ab80-8d945e430592"
                                    }
                                ],
                                "waiving_members": []
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Returns a list of all member transactions

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
ids Comma-separated member transaction IDs you would like to view

Get All Member Transactions Response

meta* object
  • 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 record in Noyo
  • version*: Current version of the record
  • created*: The date the record was created
  • modified*: The date the record was last updated
  • member_request_id*: Unique identifier of the member request in the Noyo system
  • employee_id*: Unique identifier of the associated employee in the Noyo system
  • carrier_id: Unique identifier of the carrier in the Noyo system
  • lines_of_coverage*: List of lines of coverage for the member transaction. One or more of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision
  • transaction_type*: Transaction type of the member transaction. One of: carrier_cobra_enrollment, carrier_cobra_open_enrollment, carrier_cobra_qualifying_life_event, carrier_cobra_termination, carrier_demographic, carrier_demographic_full, carrier_enrollment_snapshot_new_hire, carrier_new_hire, carrier_open_enrollment_adding, carrier_open_enrollment_full, carrier_open_enrollment_modifying, carrier_open_enrollment_removing, carrier_qualifying_life_event_adding, carrier_qualifying_life_event_full, carrier_qualifying_life_event_modifying, carrier_qualifying_life_event_removing, carrier_termination, noyo_termination
  • status*: Status of the member transaction. One of: canceled, completed, failed, processing
  • verified: The date the member transaction was verified
  • body*: Body of the member transaction
  • result*: Result of the member transaction

Groups

This object represents an insured group underneath your organization. You can retrieve it to view details such as the name of the group and the SIC code of the company.

Get Single Group

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9

Example Response

{
    "id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
    "version": "6b72d72d-cc99-4df6-8152-7183e824c80c",
    "created": 1557512389,
    "modified": 1543215342,
    "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
    "name": "Test Company",
    "sic_code": "7371",
    "dba_name": "Test Corp",
    "federal_ein": "112222222"
}

Returns the latest version of a single group based on the ID provided.

Path Parameters

group_id The unique identifier of the group to be retrieved

Get Single Group Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
organization_id* uuid Unique identifier of the platform or broker organization in Noyo
name* string Name of the group
sic_code string SIC Code of the group
dba_name string DBA name for the company, if applicable
federal_ein string Federal Employer Identification Number for the company

Get Groups

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
            "version": "6b72d72d-cc99-4df6-8152-7183e824c80c",
            "created": 1557512389,
            "modified": 1543215342,
            "organization_id": "d61fa455-adf4-4dc4-8c57-6d779ba9475e",
            "name": "Test Company",
            "sic_code": "7371",
            "dba_name": "Test Corp",
            "federal_ein": "112222222"
        }
    ]
}

Returns a list of all groups in the current user organization.

If you would like to search the groups list, you can use the company query param. It allows searches based on the group's name or dba_name values.

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
company This query param searches groups by name or dba_name values
group_ids Comma-separated list of requested UUID group IDs
carrier_id Used for filtering for a carrier-specific group ID. Filter by the Noyo carrier ID. Must be used with carrier_group_id
carrier_group_id Used for filtering for a carrier-specific group ID. Must be used with carrier_id








Filter for a carrier group ID

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups?carrier_id=3092866a-e3a7-4c6e-964c-2bc45dfe7ad0&carrier_group_id=OXNEMWQ4WkxoQ0oK

You can use the combination of a carrier_id and a carrier_group_id to filter for a carrier-specific group ID. This ID will depend on the carrier, but it will generally be a unique identifier for the group from the carrier's system.

Get Groups Response

meta* object
  • 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 record in Noyo
  • version*: Current version of the record
  • created*: The date the record was created
  • 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

Get Group Carrier Configurations

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2705bb9f-3c90-4400-a4e7-0bc9d48e677c/carrier_configurations

Example Response

[
    {
        "group_id": "2705bb9f-3c90-4400-a4e7-0bc9d48e677c",
        "carrier_id": "d0003042-eaae-4491-b219-4825456a3d16",
        "carrier_group_id": "9100084",
        "configuration": {
            "bill_groups": [
                {
                    "bill_group_description": "All Members",
                    "bill_group_number": 10001,
                    "bill_group_status": "open"
                }
            ],
            "member_groups": [
                {
                    "member_group_key": 2613038,
                    "member_group_name": "MEMBERS A",
                    "member_group_status": "open"
                },
                {
                    "member_group_key": 2613037,
                    "member_group_name": "MEMBERS B",
                    "member_group_status": "open"
                }
            ],
            "policy_number": "9100084"
        }
    }
]

Certain carriers have custom data for each group such as billing group information. This endpoint can be used to retrieve carrier-specific configuration data.

Path Parameters

group_id The unique identifier of the group for which you would like to view carrier configurations.

Query Parameters

effective_date The relative date on which to view the state of the record

Group Carrier Configuration Object

group_id* uuid Unique identifier of the group in Noyo
carrier_id* uuid Unique identifier of the carrier in Noyo
carrier_group_id* string Unique identifier for the group in the carrier system
configuration* object Carrier configuration details for the group

Get Single Contact

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts/30b74a44-d5b1-4123-a7a4-6d3aec251ba4

Example Response

{
    "id": "c2f5489d-36d1-4fb0-bf9f-105ad5dd0b3e",
    "version": "ef3fef8d-4889-40f4-a0f8-377b9dd23d98",
    "created": 1557512389,
    "modified": 1543215342,
    "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
    "first_name": "David",
    "last_name": "Smith",
    "title": "Chief People Officer",
    "email": "davidsmith@testcorp.com",
    "phone_number": "+14255551234",
    "types": [
        "company",
        "billing",
        "executive"
    ],
    "primary_contact": true
}

Returns the latest version of a single group contact based on the ID provided.

Path Parameters

group_id The unique identifier of the group the contact belongs to
contact_id The unique identifier of the contact to be retrieved

Get Single Contact Response

id* uuid Unique identifier of the group contact in Noyo
version* uuid Version of the group contact record
created* timestamp The date the record was originated
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
first_name string First name of the group contact
last_name string Last name of the group contact
title string Job title of the group contact
email string Work email address of the group contact
phone_number string Work phone number of the group contact in E.164 format
types* array List of contact types for the group contact. One of: billing, company, executive, online
primary_contact boolean True if contact is the primary contact for the group

Get Contacts

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/contacts

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 2
    },
    "response": [
        {
            "id": "c2f5489d-36d1-4fb0-bf9f-105ad5dd0b3e",
            "version": "6ba43c6e-69f2-435f-a126-8595a798eb52",
            "created": 1557512389,
            "modified": 1543215342,
            "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
            "first_name": "David",
            "last_name": "Smith",
            "title": "Chief People Officer",
            "email": "davidsmith@testcorp.com",
            "phone_number": "+14255551234",
            "types": [
                "company",
                "billing"
            ],
            "primary_contact": true
        },
        {
            "id": "7e3c1f14-e7e7-42b8-81d8-3fcd7bd7d418",
            "version": "88bfbe28-7f8b-4497-a50b-932ee3387b68",
            "created": 1557512389,
            "modified": 1543215342,
            "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
            "first_name": "Caroline",
            "last_name": "Johnson",
            "title": "VP of Human Resources",
            "email": "carolinejohnson@testcorp.com",
            "phone_number": "+14255551234",
            "types": [
                "executive"
            ],
            "primary_contact": false
        }
    ]
}

Returns a list of all group contacts for a given group.

Path Parameters

group_id The unique identifier of the group for which you would like to view contacts

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Contacts Response

meta* object
  • 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 Location

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations/bd957820-4652-4ee7-8a3a-6413df21e28d

Example Response

{
    "id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
    "version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
    "created": 1557512389,
    "modified": 1543215342,
    "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
    "address": {
        "street_one": "1234 Test Ln",
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94107",
        "county": "San Francisco"
    }
}

Returns the latest version of a single group location based on the ID provided.

Path Parameters

group_id The unique identifier of the group the location belongs to
location_id The unique identifier of the location to be retrieved

Single Location Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
display_name* string Display name for the group location
address* object
  • 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 Locations

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/locations

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 2
    },
    "response": [
        {
            "id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
            "version": "f4142cba-f3eb-4917-b3bd-123d683f18d7",
            "created": 1557512389,
            "modified": 1543215342,
            "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
            "address": {
                "street_one": "1234 Test Ln",
                "city": "San Francisco",
                "state": "CA",
                "zip_code": "94107",
                "county": "San Francisco"
            }
        }
    ]
}

Returns a list of all group locations for a given group.

Path Parameters

group_id The unique identifier of the group for which you would like to view locations

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Locations Response

meta* object
  • 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 record in Noyo
  • version*: Current version of the record
  • created*: The date the record was created
  • 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 Latest Audit

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2ce3b54a-2535-4803-b218-e6b44081d418/audit_requests/latest

Example Response

{
    "group_id": "2ce3b54a-2535-4803-b218-e6b44081d418",
    "carrier_ids": [
        "8fac0992-933a-4743-8dab-0d606ef2569e"
    ],
    "completed_at": 1602609543
}

Noyo regularly audits each Group against the carrier(s) that the Group has coverage with in order to find updated data and potential mismatches. This endpoint returns metadata about the latest group audit request that was completed. If no group audits have been completed the completed_at timestamp will be the timestamp of when the group was created and the carrier_ids array will be empty.

Path Parameters

group_id The unique identifier of the associated group in Noyo

Query Parameters

carrier_id The unique identifier of the carrier for which you would like to view audit requests

Get Latest Audit Response

group_id* uuid Unique identifier of the associated group in Noyo
carrier_ids* array List of carrier IDs included in group audit
completed_at* timestamp The date the group audit request was completed

Employees

This object represents an employee within a group. It contains personal information about the employee including name, address, contact info, etc. as well as employment related information like salary, occupation and employment status.

Create Employee

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees

Body Parameter


{
    "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
    "location_id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
    "person": {
        "first_name": "David",
        "last_name": "Johnson",
        "home_address": {
            "street_one": "1234 Home Ave",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107",
            "county": "San Francisco"
        },
        "date_of_birth": "1981-06-22",
        "ssn": "123456789",
        "sex": "M",
        "marital_status": "married",
        "contact": {
            "home_phone": "+12065551234",
            "work_phone": "+12065559876",
            "email_address": "david@testemail.com",
            "email_address_type": "home",
            "preferred_method": "email"
        }
    },
    "employment": {
        "employment_status": "full-time",
        "occupation": "Senior Analyst",
        "hours_worked": 50,
        "salary": {
            "amount": 55000,
            "unit": "annual",
            "type": "salary"
        },
        "employment_dates": {
            "hire_date": "2014-12-10",
            "full_time_start": "2015-01-01"
        },
        "work_state": "CA"
    },
    "classifications": {
        "BranchName": "HQ"
    }
}

Example Response

{
    "id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
    "created": 1626281253,
    "modified": 1626281253,
    "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
    "location_id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
    "person": {
        "first_name": "David",
        "last_name": "Johnson",
        "home_address": {
            "street_one": "1234 Home Ave",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107",
            "county": "San Francisco"
        },
        "date_of_birth": "1981-06-22",
        "ssn": "123456789",
        "sex": "M",
        "marital_status": "married",
        "contact": {
            "home_phone": "+12065551234",
            "work_phone": "+12065559876",
            "email_address": "david@testemail.com",
            "email_address_type": "home",
            "preferred_method": "email"
        }
    },
    "employment": {
        "employment_status": "full-time",
        "occupation": "Senior Analyst",
        "hours_worked": 50,
        "salary": {
            "amount": 55000,
            "unit": "annual",
            "type": "salary"
        },
        "employment_dates": {
            "hire_date": "2014-12-10",
            "full_time_start": "2015-01-01"
        }
    },
    "classifications": {
        "BranchName": "HQ"
    }
}

Create a new employee for a group.

Request Body

group_id* uuid Unique identifier of the group in Noyo
location_id uuid Unique identifier of the employee group location in Noyo
person* object
  • 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, X
  • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
  • 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. One of: home, work
    • 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:
      • disabled: True if the member has a 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)
classifications object Fields that classify employees for group structure mapping

Employee Validation


SSN Validation

When POSTing to the endpoint to create an employee or dependent, the SSN is verified to ensure the correct format. The pattern checks to make sure that the SSN is 9 digits long, that no individual section consists solely of zeros, and that the number does not start with "666". If the SSN validation fails, you will get the following response:

{ "errors": { "person": { "ssn": ["Invalid person SSN"] } } }

Create Employee Response

id* uuid Unique identifier of the employee in Noyo
custom_individual_id string The custom identifier for this employee in your system
version* uuid Version of the employee record
created* timestamp The date the record was originated
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
location_id uuid Unique identifier of the employee group location in Noyo
person* object
  • 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, X
  • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
  • 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. One of: home, work
    • 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:
      • disabled: True if the member has a 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)
classifications object Fields that classify employees for group structure mapping

Get Single Employee

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.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"
        },
        "work_state": "CA"
    }
}

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

Get Single Employee Response

id* uuid Unique identifier of the employee in Noyo
custom_individual_id string The custom identifier for this employee in your system
version* uuid Version of the employee record
created* timestamp The date the record was originated
modified* timestamp The date the record was last updated
group_id* uuid Unique identifier of the group in Noyo
location_id uuid Unique identifier of the employee group location in Noyo
person* object
  • 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, X
  • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
  • 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. One of: home, work
    • 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:
      • disabled: True if the member has a 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)
classifications object Fields that classify employees for group structure mapping

Get Employees in a Group

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/2613a221-d3c8-4c8a-86d5-e7e885fd1da9/employees

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "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

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
first_name The employee first name for which you would like to filter
last_name The employee last name for which you would like to filter
date_of_birth The ISO-8601 (YYYY-MM-DD) employee date of birth for which you would like to filter

Get All Employees

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "version": "6260146a-3486-4c3d-b2a6-fcd3f8c84043",
            "group_id": "2613a221-d3c8-4c8a-86d5-e7e885fd1da9",
            "location_id": "bd957820-4652-4ee7-8a3a-6413df21e28d",
            "person": {
                "first_name": "David",
                "last_name": "Johnson",
                "home_address": {
                    "street_one": "1234 Home Ave",
                    "city": "San Francisco",
                    "state": "CA",
                    "zip_code": "94107",
                    "county": "San Francisco"
                },
                "date_of_birth": "1981-06-22",
                "ssn": "123456789",
                "sex": "M",
                "marital_status": "single",
                "contact": {
                    "home_phone": "+12065551234",
                    "work_phone": "+12065559876",
                    "email_address": "david@testemail.com",
                    "email_address_type": "home",
                    "preferred_method": "email"
                }
            },
            "employment": {
                "employment_status": "full-time",
                "occupation": "Senior Analyst",
                "hours_worked": 50,
                "salary": {
                    "amount": 55000,
                    "unit": "annual",
                    "type": "salary"
                },
                "employment_dates": {
                    "hire_date": "2014-12-10",
                    "full_time_start": "2015-01-01"
                },
                "work_state": "CA"
            }
        }
    ]
}

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.

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1
first_name The employee first name for which you would like to filter
last_name The employee last name for which you would like to filter
date_of_birth The ISO-8601 (YYYY-MM-DD) employee date of birth for which you would like to filter

Get All Employees Response

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
  • custom_individual_id: The custom identifier for this employee in your system
  • 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, X
    • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
    • 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. One of: home, work
      • 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:
        • disabled: True if the member has a 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)
  • classifications: Fields that classify employees for group structure mapping

Filtering Employees in a Group

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.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.noyo.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")

Dependents

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.

Create Dependent

Code Sample

curl -X POST
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/dependents

Body Parameter


{
    "relationship": "child",
    "person": {
        "first_name": "Jamie",
        "last_name": "Johnson",
        "home_address": {
            "street_one": "1234 Home Ave",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107",
            "county": "San Francisco"
        },
        "date_of_birth": "2000-01-02",
        "ssn": "384032999",
        "sex": "F",
        "marital_status": "single",
        "contact": {
            "home_phone": "+12065551234",
            "email_address": "jamie@testemail.com",
            "email_address_type": "home"
        }
    }
}

Example Response

{
    "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
    "version": "669fbe16-9960-4069-91aa-832ada3f4e42",
    "created": 1626281253,
    "modified": 1626281253,
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "relationship": "child",
    "person": {
        "first_name": "Jamie",
        "last_name": "Johnson",
        "home_address": {
            "street_one": "1234 Home Ave",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107",
            "county": "San Francisco"
        },
        "date_of_birth": "2000-01-02",
        "ssn": "384032999",
        "sex": "F",
        "marital_status": "single",
        "contact": {
            "home_phone": "+12065551234",
            "email_address": "jamie@testemail.com",
            "email_address_type": "home"
        }
    }
}

Create a new dependent for an employee.

Path Parameters

employee_id The unique identifier of the employee the dependent belongs to

Request Body

relationship* string Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child
person* object
  • 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, X
  • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
  • 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. One of: home, work
    • 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:
      • disabled: True if the member has a 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 Response

id* uuid Unique identifier of the dependent in Noyo
custom_individual_id string The custom identifier for this dependent in your system
version* uuid Version of the dependent record
created* timestamp The date the record was originated
modified* timestamp The date the record was last updated
employee_id* uuid Unique identifier of the employee in Noyo
relationship* string Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child
person* object
  • 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, X
  • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
  • 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. One of: home, work
    • 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:
      • disabled: True if the member has a 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 Single Dependent

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/dependents/fd62665c-0846-4e9d-bd29-80779b5f685c

Example Response

{
    "id": "fd62665c-0846-4e9d-bd29-80779b5f685c",
    "version": "669fbe16-9960-4069-91aa-832ada3f4e42",
    "created": 1557512389,
    "modified": 1547412389,
    "employee_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "relationship": "spouse",
    "person": {
        "first_name": "Diane",
        "last_name": "Johnson",
        "home_address": {
            "street_one": "1234 Home Ave",
            "city": "San Francisco",
            "state": "CA",
            "zip_code": "94107",
            "county": "San Francisco"
        },
        "date_of_birth": "1982-01-02",
        "ssn": "987654321",
        "sex": "F",
        "marital_status": "married",
        "contact": {
            "home_phone": "+12065551234",
            "email_address": "diane@testemail.com",
            "email_address_type": "home"
        }
    }
}

Returns the latest version of a single dependent based on the ID provided.

Path Parameters

dependent_id The unique identifier of the dependent you would like to view

Get Single Dependent Response

id* uuid Unique identifier of the dependent in Noyo
custom_individual_id string The custom identifier for this dependent in your system
version* uuid Version of the dependent record
created* timestamp The date the record was originated
modified* timestamp The date the record was last updated
employee_id* uuid Unique identifier of the employee in Noyo
relationship* string Relationship of the dependent to the employee. One of: adopted-child, child, civil-union, domestic-partner, ex-spouse, foster-child, grandchild, legal-guardianship, other, spouse, step-child
person* object
  • 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, X
  • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
  • 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. One of: home, work
    • 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:
      • disabled: True if the member has a 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.noyo.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",
            "created": 1557512389,
            "modified": 1547412389,
            "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

Query Parameters

page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Dependents Response

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
  • custom_individual_id: The custom identifier for this dependent in your system
  • 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, grandchild, 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, X
    • marital_status: Marital status of the person. One of: divorced, domestic-partner, legally-separated, married, single, widowed
    • 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. One of: home, work
      • 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:
        • disabled: True if the member has a 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.noyo.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",
    "created": 1557512389,
    "modified": 1543215342
}

Returns the latest version of a single group enrollment based on the ID provided.

Path Parameters

enrollment_id Unique identifier of the group enrollment

Get Single Group Enrollment Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_id* uuid Unique identifier of the associated group in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in the Noyo system
line_of_coverage* string Line of coverage for the group enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, 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
open_enrollment_renewal_date date ISO-8601 date string for the open enrollment renewal start date of the group enrollment
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Get Group Enrollments

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.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",
            "created": 1557512389,
            "modified": 1543215342
        },
        {
            "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",
            "created": 1557512389,
            "modified": 1543215342
        }
    ]
}

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

Query Parameters

effective_date The relative date on which to view the state of the record
status The status of the group enrollments you would like to view
page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Group Enrollments Response

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 record in Noyo
  • version*: Current version of the record
  • group_id*: Unique identifier of the associated group in the Noyo system
  • carrier_id*: Unique identifier of the associated carrier in the Noyo system
  • line_of_coverage*: Line of coverage for the group enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, 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
  • open_enrollment_renewal_date: ISO-8601 date string for the open enrollment renewal start date of the group enrollment
  • effective_start_date: ISO-8601 date string for the effective start date of the record
  • effective_end_date: ISO-8601 date string for the effective end date of the record
  • created*: The date the record was created
  • modified*: The date the record was last updated

Group Plans

These objects represent a plan or benefit offered by a carrier and available to employee or dependent members of a group.

The Group Plan Objects

Group Accident Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group accident plan
name* string Name of the group accident plan
code string Plan code of the group accident plan
plan_type* string Type of group accident plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group accident plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group accident plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group accident plan
termination_policy* string Termination policy for the group accident plan. One of: end_of_month, fifteenth_of_month, last_work_date
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group AD&D Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group AD&D plan
name* string Name of the group AD&D plan
code string Plan code of the group AD&D plan
plan_type* string Type of group AD&D plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group AD&D plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group AD&D plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group AD&D plan
termination_policy* string Termination policy for the group AD&D plan. One of: end_of_month, fifteenth_of_month, last_work_date
volume_rules* object Volume rules for the group AD&D plan
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group Cancer Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group cancer plan
name* string Name of the group cancer plan
code string Plan code of the group cancer plan
plan_type* string Type of group cancer plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group cancer plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group cancer plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group cancer plan
termination_policy* string Termination policy for the group cancer plan. One of: end_of_month, fifteenth_of_month, last_work_date
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group Critical Illness Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group critical illness plan
name* string Name of the group critical illness plan
code string Plan code of the group critical illness plan
plan_type* string Type of group critical illness plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group critical illness plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group critical illness plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group critical illness plan
termination_policy* string Termination policy for the group critical illness plan. One of: end_of_month, fifteenth_of_month, last_work_date
volume_rules* object Volume rules for the group critical illness plan
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group Dental Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group dental plan
name* string Name of the group dental plan
code string Plan code of the group dental plan
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
plan_type string Type of group dental plan. One of: aso, dhmo, epo, indemnity, pos, ppo
network string Network name of the plan designated by the carrier
voluntary boolean True if the group dental plan is a voluntary plan
status* string Status of the group dental plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group dental plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group dental plan
termination_policy* string Termination policy for the group dental plan. One of: end_of_month, fifteenth_of_month, last_work_date
cobra_rules* object
  • eligible: True if group plan is eligible for COBRA enrollments
created* timestamp The date the record was created
modified* timestamp The date the record was last updated
plan_configuration* object Group plan configuration details

Group Hospital Indemnity Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group hospital indemnity plan
name* string Name of the group hospital indemnity plan
code string Plan code of the group hospital indemnity plan
plan_type* string Type of group hospital indemnity plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group hospital indemnity plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group hospital indemnity plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group hospital indemnity plan
termination_policy* string Termination policy for the group hospital indemnity plan. One of: end_of_month, fifteenth_of_month, last_work_date
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group Life Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group life plan
name* string Name of the group life plan
code string Plan code of the group life plan
plan_type* string Type of group life plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group life plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group life plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group life plan
termination_policy* string Termination policy for the group life plan. One of: end_of_month, fifteenth_of_month, last_work_date
volume_rules* object Volume rules for the group life plan
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group LTD Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group LTD plan
name* string Name of the group LTD plan
code string Plan code of the group LTD plan
plan_type* string Type of group LTD plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group LTD plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group LTD plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group LTD plan
termination_policy* string Termination policy for the group LTD plan. One of: end_of_month, fifteenth_of_month, last_work_date
volume_rules* object Volume rules for the group LTD plan
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group Medical Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group medical plan
name* string Name of the group medical plan
code string Plan code of the group medical plan
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
plan_type string Type of group medical plan. One of: epo, hdhp, hmo, hmp, pos, ppo
network string Network name of the plan designated by the carrier
metal_tier string Metal tier designation of the group medical plan. One of: bronze, gold, platinum, silver
status* string Status of the group medical plan. One of: active, discontinued, pending
eligible_member_types array Eligible member types for the group medical plan
waiting_periods* array Member waiting period details for the group medical plan
termination_policy* string Termination policy for the group medical plan. One of: end_of_month, fifteenth_of_month, last_work_date
cobra_rules* object
  • eligible: True if group plan is eligible for COBRA enrollments
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group STD Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group STD plan
name* string Name of the group STD plan
code string Plan code of the group STD plan
plan_type* string Type of group STD plan. One of: basic, voluntary
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
status* string Status of the group STD plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group STD plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group STD plan
termination_policy* string Termination policy for the group STD plan. One of: end_of_month, fifteenth_of_month, last_work_date
volume_rules* object Volume rules for the group STD plan
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Group Vision Plan Object

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the associated group enrollment in the Noyo system
carrier_id* uuid Unique identifier of the associated carrier in Noyo
line_of_coverage* string Line of coverage for the group vision plan
name* string Name of the group vision plan
code string Plan code of the group vision plan
effective_start_date date ISO-8601 date string for the effective start date of the record
effective_end_date date ISO-8601 date string for the effective end date of the record
voluntary boolean True if the group vision plan is a voluntary plan
status* string Status of the group vision plan. One of: active, discontinued, pending
eligible_member_types* array List of member types eligible for the group vision plan. One of: all, child, domestic-partner, employee, spouse
waiting_periods* array Member waiting period details for the group vision plan
termination_policy* string Termination policy for the group vision plan. One of: end_of_month, fifteenth_of_month, last_work_date
cobra_rules* object
  • eligible: True if group plan is eligible for COBRA enrollments
plan_configuration* object Group plan configuration details
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

Get Single Plan

Note that the response plan will be nested in a plan attribute. The response will conform to one of the plan objects by line of coverage.

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/plans/31559b4b-e45a-4df8-84f6-2220d7ed0c3a

Example Response

{
    "plan": {
        "cobra_rules": {
            "eligible": false
        },
        "code": "D1",
        "created": 1554175253,
        "effective_end_date": "9999-12-31",
        "effective_start_date": "2020-01-01",
        "eligible_member_types": [
            "employee"
        ],
        "group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
        "id": "5ba915fc-afe8-4572-a60f-61ee5883e100",
        "line_of_coverage": "dental",
        "modified": 1554175253,
        "name": "Dental - Employee",
        "network": "Dental PPO Network",
        "plan_type": "ppo",
        "status": "active",
        "termination_policy": "end_of_month",
        "version": "1bf06a82-8d81-4849-91d3-47c60fdce605",
        "voluntary": false,
        "waiting_periods": [
            {
                "waiting_period_enrollment_type": "new_member",
                "waiting_period_rule": "hire_date"
            },
            {
                "waiting_period_amount": 0,
                "waiting_period_enrollment_type": "current_member",
                "waiting_period_rule": "after_waiting_period",
                "waiting_period_unit": "day"
            }
        ]
    }
}

Returns the group plan specified by unique identifier

Path Parameters

plan_id The unique identifier of the group plan you would like to view

Query Parameters

effective_date The relative date on which to view the state of the record

Get Group Plans

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/31559b4b-e45a-4df8-84f6-2220d7ed0c3a/plans

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 2
    },
    "response": [
        {
            "cobra_rules": {
                "eligible": false
            },
            "code": "D1",
            "created": 1554175253,
            "effective_end_date": "9999-12-31",
            "effective_start_date": "2020-01-01",
            "eligible_member_types": [
                "employee"
            ],
            "group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
            "id": "5ba915fc-afe8-4572-a60f-61ee5883e100",
            "line_of_coverage": "dental",
            "modified": 1554175253,
            "name": "Dental - Employee",
            "network": "Dental PPO Network",
            "plan_type": "ppo",
            "status": "active",
            "termination_policy": "end_of_month",
            "version": "1bf06a82-8d81-4849-91d3-47c60fdce605",
            "voluntary": false,
            "waiting_periods": [
                {
                    "waiting_period_enrollment_type": "new_member",
                    "waiting_period_rule": "hire_date"
                },
                {
                    "waiting_period_amount": 0,
                    "waiting_period_enrollment_type": "current_member",
                    "waiting_period_rule": "after_waiting_period",
                    "waiting_period_unit": "day"
                }
            ]
        },
        {
            "cobra_rules": {
                "eligible": false
            },
            "code": "D1",
            "created": 1554175253,
            "effective_end_date": "9999-12-31",
            "effective_start_date": "2020-01-01",
            "eligible_member_types": [
                "spouse",
                "child"
            ],
            "group_enrollment_id": "31559b4b-e45a-4df8-84f6-2220d7ed0c3a",
            "id": "c1279c1c-ed61-439b-bd9c-07f3228c09cb",
            "line_of_coverage": "dental",
            "modified": 1554175253,
            "name": "Dental - Dependent",
            "network": "Dental PPO Network",
            "plan_type": "ppo",
            "status": "active",
            "termination_policy": "end_of_month",
            "version": "a6404fb2-f266-45b0-a6b7-84b047f017cf",
            "voluntary": false,
            "waiting_periods": [
                {
                    "waiting_period_enrollment_type": "new_member",
                    "waiting_period_rule": "hire_date"
                },
                {
                    "waiting_period_amount": 0,
                    "waiting_period_enrollment_type": "current_member",
                    "waiting_period_rule": "after_waiting_period",
                    "waiting_period_unit": "day"
                }
            ]
        }
    ]
}

Returns a list of all plans for a given group.

Path Parameters

group_id The unique identifier of the group for which you would like to view plans

Query Parameters

status Status of the group plans for which you would like to filter
line_of_coverage Line of coverage of the group plans for which you would like to filter
carrier_id The unique identifier of the carrier of the group plans for which you would like to filter
effective_date The relative date on which to view the state of the record
page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Group Plan Waiting Periods

Each group plan may include one or more waiting period rules, based on any waiting period information made available by the carrier.

Each waiting period will always have a waiting_period_enrollment_type field. The waiting_period_enrollment_type determines when the waiting period is used: new_member applies to new members enrolling as new hires, current_member applies to existing members enrolling with a QLE, and rehire applies to previously active members re-enrolling as a rehire.

Each waiting period will always have a waiting_period_rule field. This field is a general description of the waiting period rule, and determines which other fields will be present in the waiting period response.

Some waiting period rules have a waiting_period_coinciding flag. This flag is relevant when the rule defines a specific date for starting coverage and the member waiting period may end on that date. For example, the waiting period rule may be '1st of month after hire date' with a member hire date of January 1st. When waiting_period_coinciding is true, the member would begin coverage immediately in the coinciding period, e.g. January 1st. When waiting_period_coinciding is false, the member coverage would be pushed out to the following period, e.g. February 1st.

Fixed Waiting Period Object

waiting_period_enrollment_type* string Enrollment type to decide which relevant waiting period should be applied. One of: current_member, new_member, rehire
waiting_period_rule* string Waiting period rule describing the waiting period for the member. One of: hire_date

Fixed Coinciding Waiting Period Object

waiting_period_enrollment_type* string Enrollment type to decide which relevant waiting period should be applied. One of: current_member, new_member, rehire
waiting_period_rule* string Waiting period rule describing the waiting period for the member. One of: fifteenth_of_month_after_event, fifteenth_of_month_after_hire_date, first_of_month_after_event, first_of_month_after_hire_date, first_or_fifteenth_of_month_after_event, first_or_fifteenth_of_month_after_hire_date
waiting_period_coinciding* boolean True if the effective date can equal the final day of waiting period

Variable Waiting Period Object

waiting_period_enrollment_type* string Enrollment type to decide which relevant waiting period should be applied. One of: current_member, new_member, rehire
waiting_period_rule* string Waiting period rule describing the waiting period for the member. One of: after_waiting_period
waiting_period_amount* integer Amount of time required for the waiting period
waiting_period_unit* string Unit of time required for the waiting period. One of: business_day, day, month, week, year

Variable Coinciding Waiting Period Object

waiting_period_enrollment_type* string Enrollment type to decide which relevant waiting period should be applied. One of: current_member, new_member, rehire
waiting_period_rule* string Waiting period rule describing the waiting period for the member. One of: fifteenth_of_month_after_waiting_period, first_of_month_after_waiting_period, first_or_fifteenth_of_month_after_waiting_period
waiting_period_amount* integer Amount of time required for the waiting period
waiting_period_unit* string Unit of time required for the waiting period. One of: business_day, day, month, week, year
waiting_period_coinciding* boolean True if the effective date can equal the final day of waiting period

Individual Enrollments

This object represents an individual's (employee or dependent) relationship with enrolling or waiving a line of coverage with a carrier. These are the end-product of member requests submitted through this API. They are not directly created from end-user API actions.

Single Individual Enrollment

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/individual_enrollments/6670f290-4236-4690-bece-a110f9ad924b

Example Response

{
    "id": "6670f290-4236-4690-bece-a110f9ad924b",
    "version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
    "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
    "line_of_coverage": "medical",
    "status": "active",
    "individual_type": "employee",
    "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
    "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
    "enroll_data": {
        "premium": {
            "amount": 50,
            "unit": "Month"
        }
    },
    "effective_start_date": "2018-10-01",
    "effective_end_date": "2019-10-01",
    "cobra_enrollment": {},
    "individual_enrollment_configuration": {},
    "created": 1557512389,
    "modified": 1564440756
}

Returns the latest version of a single individual enrollment based on the ID provided.

Path Parameters

individual_enrollment_id Unique identifier of the individual enrollment

Query Parameters

effective_date The relative date on which to view the state of the record

Get Single Individual Enrollment Response

id* uuid Unique identifier of the record in Noyo
version* uuid Current version of the record
group_enrollment_id* uuid Unique identifier of the group enrollment in Noyo
line_of_coverage* string Line of coverage for the individual enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, life, ltd, medical, std, vision
status* string Status of the individual enrollment. One of: active, pending, terminated, waived
individual_type* string Type of member for the individual enrollment. One of: dependent, employee
individual_id* uuid Unique identifier of the employee or dependent in Noyo
plan_id* uuid Unique identifier of the group plan in Noyo
enroll_data* object Line of coverage specific enroll data with volume information
effective_start_date date ISO-8601 date string for the effective date of the coverage
effective_end_date date ISO-8601 date string for the effective date of the coverage
cobra_enrollment* object
  • cobra_enrolled: True if member is enrolled in COBRA coverage
  • cobra_type: Type of COBRA enrollment for the member. One of: federal, state
individual_enrollment_configuration* object Carrier-specific details describing the individual enrollment configuration
created* timestamp The date the record was created
modified* timestamp The date the record was last updated

By Group

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/groups/f8de4493-3c51-4337-8fdc-f00bb1ae89bd/individual_enrollments

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "6670f290-4236-4690-bece-a110f9ad924b",
            "version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
            "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
            "line_of_coverage": "medical",
            "status": "active",
            "individual_type": "employee",
            "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
            "enroll_data": {
                "premium": {
                    "amount": 50,
                    "unit": "Month"
                }
            },
            "effective_start_date": "2019-01-01",
            "effective_end_date": "2019-12-31",
            "cobra_enrollment": {
                "cobra_enrolled": true,
                "cobra_type": "federal"
            },
            "individual_enrollment_configuration": {},
            "created": 1557512389,
            "modified": 1564440756
        }
    ]
}

Returns a list of all individual enrollments for a given group.

Path Parameters

group_id Unique identifier of the associated group in the Noyo system

Query Parameters

effective_date The relative date on which to view the state of the record
page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Individual Enrollments By Group Response

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 record in Noyo
  • version*: Current version of the record
  • group_enrollment_id*: Unique identifier of the group enrollment in Noyo
  • line_of_coverage*: Line of coverage for the individual enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, 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 with volume information
  • 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
  • cobra_enrollment*:
    • cobra_enrolled: True if member is enrolled in COBRA coverage
    • cobra_type: Type of COBRA enrollment for the member. One of: federal, state
  • individual_enrollment_configuration*: Carrier-specific details describing the individual enrollment configuration
  • created*: The date the record was created
  • modified*: The date the record was last updated

By Group Enrollment

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/group_enrollments/bf129409-1f0a-4f1a-b756-14471ef733c3/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": "bf129409-1f0a-4f1a-b756-14471ef733c3",
            "line_of_coverage": "medical",
            "status": "active",
            "individual_type": "employee",
            "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
            "enroll_data": {
                "premium": {
                    "amount": 50,
                    "unit": "Month"
                }
            },
            "effective_start_date": "2019-01-01",
            "effective_end_date": "2019-12-31",
            "cobra_enrollment": {
                "cobra_enrolled": true,
                "cobra_type": "federal"
            },
            "individual_enrollment_configuration": {},
            "created": 1557512389,
            "modified": 1564440756
        }
    ]
}

Returns a list of all individual enrollments for a given group enrollment.

Path Parameters

group_enrollment_id Unique identifier of the associated group enrollment in the Noyo system

Query Parameters

effective_date The relative date on which to view the state of the record
page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Individual Enrollments By Group Enrollment Response

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 record in Noyo
  • version*: Current version of the record
  • group_enrollment_id*: Unique identifier of the group enrollment in Noyo
  • line_of_coverage*: Line of coverage for the individual enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, 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 with volume information
  • 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
  • cobra_enrollment*:
    • cobra_enrolled: True if member is enrolled in COBRA coverage
    • cobra_type: Type of COBRA enrollment for the member. One of: federal, state
  • individual_enrollment_configuration*: Carrier-specific details describing the individual enrollment configuration
  • created*: The date the record was created
  • modified*: The date the record was last updated

By Employee

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/employees/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/individual_enrollments

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "6670f290-4236-4690-bece-a110f9ad924b",
            "version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
            "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
            "line_of_coverage": "medical",
            "status": "active",
            "individual_type": "employee",
            "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
            "enroll_data": {
                "premium": {
                    "amount": 50,
                    "unit": "Month"
                }
            },
            "effective_start_date": "2018-10-01",
            "effective_end_date": "2019-10-01",
            "cobra_enrollment": {},
            "individual_enrollment_configuration": {},
            "created": 1557512389,
            "modified": 1564440756
        }
    ]
}

Returns a list of all individual enrollments for a given employee.

Path Parameters

employee_id The unique identifier of the employee for which you would like to view individual enrollments

Query Parameters

effective_date The relative date on which to view the state of the record
include_dependents Boolean, use "true" to include dependent individual enrollments in the results
page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Individual Enrollments By Employee Response

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 record in Noyo
  • version*: Current version of the record
  • group_enrollment_id*: Unique identifier of the group enrollment in Noyo
  • line_of_coverage*: Line of coverage for the individual enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, 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 with volume information
  • 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
  • cobra_enrollment*:
    • cobra_enrolled: True if member is enrolled in COBRA coverage
    • cobra_type: Type of COBRA enrollment for the member. One of: federal, state
  • individual_enrollment_configuration*: Carrier-specific details describing the individual enrollment configuration
  • created*: The date the record was created
  • modified*: The date the record was last updated

By Dependent

Code Sample

curl -X GET
 --header "Authorization: Bearer <ACCESS_TOKEN>"
 https://fulfillment.noyo.com/api/v1/dependents/30b74a44-d5b1-4123-a7a4-6d3aec251ba4/individual_enrollments

Example Response

{
    "meta": {
        "offset": 0,
        "page_num": 1,
        "page_size": 20,
        "total_records": 1
    },
    "response": [
        {
            "id": "6670f290-4236-4690-bece-a110f9ad924b",
            "version": "27bbf929-78ca-4339-8bb3-39b75f92c4a4",
            "group_enrollment_id": "7499ea07-76c9-40f2-992b-952259e98384",
            "line_of_coverage": "medical",
            "status": "active",
            "individual_type": "dependent",
            "individual_id": "30b74a44-d5b1-4123-a7a4-6d3aec251ba4",
            "plan_id": "b988cd26-121a-4dd6-b0be-09399f6ecc0a",
            "enroll_data": {
                "premium": {
                    "amount": 50,
                    "unit": "Month"
                }
            },
            "effective_start_date": "2018-10-01",
            "effective_end_date": "2019-10-01",
            "cobra_enrollment": {},
            "individual_enrollment_configuration": {},
            "created": 1557512389,
            "modified": 1564440756
        }
    ]
}

Returns a list of all individual enrollments for a given dependent.

Path Parameters

dependent_id The unique identifier of the employee for which you would like to view individual enrollments

Query Parameters

effective_date The relative date on which to view the state of the record
page_size The max size of each page of results
offset The integer offset at which to start the page. Possible values are 0 to total_records - 1

Get Individual Enrollments By Dependent Response

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 record in Noyo
  • version*: Current version of the record
  • group_enrollment_id*: Unique identifier of the group enrollment in Noyo
  • line_of_coverage*: Line of coverage for the individual enrollment. One of: accident, add, cancer, critical_illness, dental, hospital_indemnity, 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 with volume information
  • 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
  • cobra_enrollment*:
    • cobra_enrolled: True if member is enrolled in COBRA coverage
    • cobra_type: Type of COBRA enrollment for the member. One of: federal, state
  • individual_enrollment_configuration*: Carrier-specific details describing the individual enrollment configuration
  • created*: The date the record was created
  • modified*: The date the record was last updated