API Basics

The core objects and other details you need to know

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.”


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.


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_sizeNumber of records returned in the list, defaults to 20, must be at least 5, cannot exceed 100
offsetThe entry in the list at which to begin returning results, defaults to 0

Paginated Result

metaoffset: 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
responseArray of records in the list, structure will vary by endpoint.

Example code

Code sample for querying for a paginated list of groups.

curl -X GET
 --header "Content-Type: application/json"
 --header "Authorization: Bearer <ACCESS_TOKEN>"

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"

OpenAPI Spec

In addition to these guides, we also have a JSON OpenAPI spec for Noyo services. You can import this file into your own tools to understand the API interface better and build clients.


Carrier Documentation

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

What’s Next

Learn how to interact with Noyo data