Using the API

Before you start your integration, it’s important to be familiar with the following concepts used throughout our API documentation and guides.

Core Objects

Familiarize yourself with the following core objects and how they may relate to the way data is represented in your system:

Groups
The group offering coverage. May be known as a “company” or “employer.”
Group Plans
The plan offered by the group. May be known as a “product” or “coverage.”
Employees + Dependents
The individuals enrolling in coverage. Employees may be known as “members” or “subscribers.”
Individual Enrollments
The individual’s coverage details for one plan. May be known as an “individual coverage.”

Datetimes

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.

Pagination

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

Paginated Result

Field	Description
`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 for the current page

Example code

Code sample for querying for a paginated list of groups.

Request

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

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

Carrier Documentation

Noyo’s carrier network along with carrier-specific documentation (including supported endpoints, field-level requirements, and business rules) is available in the Noyo web application.

Unset Fields

When sending an optional field with no set value, Noyo recommends omitting the key rather than sending the key with value null.

Not Recommended

{
  "line_of_coverage": "medical",
  "volume": null // not recommended 
}

Intro

Groups

Members & Changes

Legacy

Core Objects

Datetimes

Query Parameters

Paginated Result

Example code

Carrier Documentation

Unset Fields

​Core Objects

​Datetimes

​Pagination

​Query Parameters

​Paginated Result

​Example code

​Carrier Documentation

​Unset Fields

Core Objects

Datetimes

Pagination

Query Parameters

Paginated Result

Example code

Carrier Documentation

Unset Fields