Noyo Groups API
The Groups API from Noyo — 7 operation(s) for groups.
OpenAPI Specification
openapi: 3.0.1
info:
description: APIs to manage and consume information about Carriers
title: Noyo Carrier Carrier Mapped Field Groups API
version: 1.0.0
servers: []
tags:
- name: Groups
paths:
/ui/v1/groups:
x-summary: List Groups, by authenticated organization
get:
description: Returns a list of all groups
operationId: uiGetGroupList
parameters:
- description: Comma-separated list of requested UUID group IDs
in: query
name: group_ids
required: false
schema:
type: string
- description: The max size of each page of results
in: query
name: page_size
required: false
schema:
type: integer
- description: The integer offset at which to start the page. Possible values are 0 to total_records - 1
in: query
name: offset
required: false
schema:
type: integer
- in: query
name: name
required: false
schema:
type: string
- description: Used for filtering for a carrier-specific group ID. Must be used with carrier_group_id.
in: query
name: carrier_id
required: false
schema:
type: integer
- description: Used for filtering for organization-specific groups
in: query
name: organization_id
required: false
schema:
example: a88f4b6f-7c26-4dd0-8b62-6c76f06412ad
format: uuid
type: string
- description: Used for filtering for a carrier-specific group ID. Must be used with carrier_id.
in: query
name: carrier_group_id
required: false
schema:
type: string
- description: Searches groups for name or dba_name values that contain the search term
in: query
name: company
required: false
schema:
type: string
- description: Searches groups for name or dba_name values that start with the search term
in: query
name: name_starts_with
required: false
schema:
type: string
responses:
'200':
content:
application/json:
example:
meta:
offset: 0
page_num: 1
page_size: 20
total_records: 2
response:
- group:
created: 1554177876
dba_name: Test Corp
federal_ein: '112222222'
id: 2613a221-d3c8-4c8a-86d5-e7e885fd1da9
is_protected_group: true
modified: 1554177876
name: Test Company
organization_id: d61fa455-adf4-4dc4-8c57-6d779ba9475e
protected_at: 1554177876
sic_code: '7371'
version: 6b72d72d-cc99-4df6-8152-7183e824c80c
group_enrollments:
- carrier_id: 8fac0992-933a-4743-8dab-0d606ef2569e
effective_end_date: '2019-12-31'
effective_start_date: '2019-01-01'
group_id: 2613a221-d3c8-4c8a-86d5-e7e885fd1da9
id: 7499ea07-76c9-40f2-992b-952259e98384
line_of_coverage: medical
open_enrollment_end_date: '2019-02-01'
open_enrollment_start_date: '2019-01-01'
status: active
version: c2292b67-0382-45e9-a378-b52c4129f672
locations:
- created: 1557862286
display_name: Company Location (10001)
group_id: 2613a221-d3c8-4c8a-86d5-e7e885fd1da9
id: a42a8cf5-d0dd-4701-af92-aa945c71f6da
modified: 1557862286
version: 51d8edbc-2999-4b5e-b524-7a53332f0a0a
- group:
created: 1554177876
dba_name: Lawyer Corp
federal_ein: '113333333'
id: 3c970610-e2f8-428a-bb20-89b74e319b60
is_protected_group: false
modified: 1554177876
name: We R Good Lawyers, LLP
organization_id: d61fa455-adf4-4dc4-8c57-6d779ba9475e
sic_code: '7371'
version: 6b72d72d-cc99-4df6-8152-7183e824c80c
group_enrollments:
- carrier_id: 8fac0992-933a-4743-8dab-0d606ef2569e
effective_end_date: '2019-12-31'
effective_start_date: '2019-01-01'
group_id: 3c970610-e2f8-428a-bb20-89b74e319b60
id: 453dbb34-30cb-40f4-92b3-b4e3dcb5ac60
line_of_coverage: medical
open_enrollment_end_date: '2019-02-01'
open_enrollment_start_date: '2019-01-01'
status: active
version: cfe31ac3-1c60-416c-9b79-7fad2f6cba5e
locations:
- created: 1557862286
display_name: Company Location (10001)
group_id: 3c970610-e2f8-428a-bb20-89b74e319b60
id: ec58c8c6-6b9b-45d0-a8fa-6a940681d39a
modified: 1557862286
version: 28a23680-a48e-4756-a02b-5ff3a72e36d3
schema:
$ref: '#/components/schemas/PaginatedUIGroupResult'
description: Successful Response - Returns all matching Groups
summary: Get a list of all Groups
tags:
- Groups
/ui/v1/groups/{group_id}:
x-summary: Get Single Group
get:
description: Returns the latest version of a single group based on the ID provided.
operationId: uiGetGroup
parameters:
- in: path
name: group_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
example:
group:
created: 1554177876
custom_identifiers: {}
id: 2613a221-d3c8-4c8a-86d5-e7e885fd1da9
is_protected_group: true
modified: 1554177876
name: Test Company
organization_id: d61fa455-adf4-4dc4-8c57-6d779ba9475e
protected_at: 1554177876
version: 4313a221-d3c8-4c8a-86d5-e7e885fd1da9
group_enrollments:
- carrier_id: 8fac0992-933a-4743-8dab-0d606ef2569e
created: 1554177876
effective_end_date: '2019-12-31'
effective_start_date: '2019-01-01'
group_id: 2613a221-d3c8-4c8a-86d5-e7e885fd1da9
id: 7499ea07-76c9-40f2-992b-952259e98384
line_of_coverage: medical
modified: 1554177876
open_enrollment_end_date: '2019-02-01'
open_enrollment_start_date: '2019-01-01'
status: active
version: c2292b67-0382-45e9-a378-b52c4129f672
locations:
- address:
city: Des Moines
county: ''
state: IA
street_one: 123 Street
street_two: ''
zip_code: '50392'
created: 1557862286
display_name: Company Location (10001)
group_id: 2613a221-d3c8-4c8a-86d5-e7e885fd1da9
id: a42a8cf5-d0dd-4701-af92-aa945c71f6da
modified: 1557862286
version: 51d8edbc-2999-4b5e-b524-7a53332f0a0a
plans:
dental:
- carrier_id: d0003042-eaae-4491-b219-4825456a3d16
cobra_rules: {}
code: D1
created: 1554175253
effective_end_date: '2020-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
network: Dental PPO Network
plan_type: ppo
status: active
termination_policy: last_work_date
version: 1bf06a82-8d81-4849-91d3-47c60fdce605
voluntary: false
waiting_periods: []
schema:
$ref: '#/components/schemas/UIGroupParentResult'
description: Successful Response - Returns a single Group
summary: Get a single Group
tags:
- Groups
/ui/v1/groups/{group_id}/carriers:
x-summary: Get Group Carriers
get:
description: Returns a list of carrier IDs
operationId: uiGetGroupCarriers
parameters:
- description: The unique identifier of the group.
in: path
name: group_id
required: true
schema:
example: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
format: uuid
type: string
- description: Whether to filter the list of carriers to those eligible for disconnection
in: query
name: disconnection_eligible
required: false
schema:
type: boolean
responses:
'200':
content:
application/json:
example:
- 99c7b0ea-6222-47cc-acfb-69cef43e4be3
- d0003042-eaae-4491-b219-4825456a3d16
schema:
items:
type: string
type: array
description: Successful Response - Returns all of the Group's carriers
summary: Get a list of all Carriers for a Group
tags:
- Groups
/ui/v1/groups/{group_id}/group_plans:
x-summary: Get All Group Plans
get:
description: Returns a list of all group plans
operationId: uiGetGroupPlansList
parameters:
- in: path
name: group_id
required: true
schema:
type: string
- description: The max size of each page of results
in: query
name: page_size
required: false
schema:
type: integer
- description: The integer offset at which to start the page. Possible values are 0 to total_records - 1
in: query
name: offset
required: false
schema:
type: integer
responses:
'200':
content:
application/json:
example:
meta:
offset: 0
page_num: 1
page_size: 20
total_records: 2
response:
- carrier_id: c62a7be4-1551-4fb5-90c0-151121be785b
group_enrollment_id: 227894df-ae68-45b3-bce8-6a7717a8fcf7
id: 002bd568-6f05-4a71-8293-4d16562a430f
line_of_coverage: medical
name: SuperAwesome Medical Plan
- carrier_id: c62a7be4-1551-4fb5-90c0-151121be785b
group_enrollment_id: 539b60cc-d9cb-4554-834d-e63a4f6a1c54
id: aaeeeaa3-0916-40b6-a639-5c19c0584e14
line_of_coverage: dental
name: PrettyNice Dental Plan
schema:
$ref: '#/components/schemas/PaginatedUIGroupPlanResult'
description: Successful Response - Returns all matching group plans
summary: Get a list of all Group Plans
tags:
- Groups
/ui/v1/groups/{group_id}/mappable_fields:
x-summary: Get Mappable Fields
get:
operationId: uiGetGroupMappableFields
parameters:
- description: The unique identifier of the group.
in: path
name: group_id
required: true
schema:
example: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
format: uuid
type: string
- description: The relative date on which to view the state of the record
in: query
name: effective_date
required: false
schema:
type: string
- description: Unique identifier of the carrier in Noyo
in: query
name: carrier_id
required: true
schema:
example: d0003042-eaae-4491-b219-4825456a3d16
format: uuid
type: string
- description: The max size of each page of results
in: query
name: page_size
required: false
schema:
type: integer
- description: The integer offset at which to start the page. Possible values are 0 to total_records - 1
in: query
name: offset
required: false
schema:
type: integer
responses:
'200':
content:
application/json:
example:
meta:
offset: 0
page_num: 1
page_size: 20
total_records: 2
response:
- configurable_values:
- bill_group_description: Some Members
bill_group_number: 10001
bill_group_status: open
- bill_group_description: Other members
bill_group_number: 10002
bill_group_status: open
mapped_field:
carrier_id: d0003042-eaae-4491-b219-4825456a3d16
id: 79020524-c77d-4b13-b96f-88b3e26eb54d
mapped_field: bill_group_number
object_name: bill_groups
version: ac5e9ad8-ce8a-4d3b-b7fa-830a67aef4ea
- configurable_values:
- member_group_key: 10001
member_group_name: Some Members
member_group_status: open
- member_group_key: 10002
member_group_name: Other members
member_group_status: open
mapped_field:
carrier_id: d0003042-eaae-4491-b219-4825456a3d16
id: dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1
mapped_field: member_group_key
object_name: member_groups
version: 5200a894-81c5-4c41-8519-86c32e9a9965
schema:
$ref: '#/components/schemas/PaginatedUIGroupMappableFieldsResult'
description: Successful Response - Returns all possible mappable fields
summary: Get a list of all Mappable Fields for the Group and Carrier
tags:
- Groups
/ui/v1/groups/{group_id}/platform_group_structure:
x-summary: Get Platform Group Structure
get:
operationId: UIGroupPlatformGroupStructureResult
parameters:
- description: The unique identifier of the group.
in: path
name: group_id
required: true
schema:
example: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
format: uuid
type: string
responses:
'200':
content:
application/json:
example:
created: 1744662582
group_id: d2a929df-b5f2-4374-bfdf-18ac610494b8
id: 0599efad-8b03-4395-b91d-2da3cdc5dea6
modified: 1744662582
organization_id: ce7d8907-a834-406e-83bd-c180fcc05bdc
structure:
plans:
- carrier_id: 9a0a7437-4097-4251-9e71-85384c0eb1c9
id: 7ae064ed-330d-44bf-910f-4fa6438a9897
line_of_coverage: dental
name: dental
temporals:
- configuration:
department_number:
- '1'
end_date: '2026-01-01'
start_date: '2025-01-01'
version: 3fa18941-00f1-412b-b4d1-c70f6493f95b
schema:
$ref: '#/components/schemas/UIGroupPlatformGroupStructureResult'
description: Successful Response - Returns a platform group structure
summary: Get Platform Group Structure
tags:
- Groups
/ui/v1/groups/{group_id}/platform_mapping:
x-summary: Get Platform Account Structure and Group Mapping
get:
operationId: uiGetGroupPlatformMapping
parameters:
- description: The unique identifier of the group.
in: path
name: group_id
required: true
schema:
example: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
format: uuid
type: string
- description: The relative date on which to view the state of the record
in: query
name: effective_date
required: false
schema:
type: string
- description: Unique identifier of the carrier in Noyo
in: query
name: carrier_id
required: true
schema:
example: d0003042-eaae-4491-b219-4825456a3d16
format: uuid
type: string
responses:
'200':
content:
application/json:
example:
group_mapping:
carrier_id: 4d4d815b-ae8f-430c-901f-1c9d5ee3f4f1
effective_end_date: '2999-12-31'
effective_start_date: '2021-01-01'
group_id: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
id: dd9a1813-34f7-4c7e-86bc-f041f2cbd9a1
status: ready
version: 65b729f8-de9a-4c9b-bed9-2df020dbbfa4
group_name: Test Company
platform_account_structure:
account_structure:
account_structure_fields:
- existing_value_set:
- North Branch
- HQ
- Springfield
field_name: BranchName
field_type: string
plans:
group_dental_plans:
- Dental Plan Low
- Dental Plan High
group_medical_plans:
- Medical Plan A
- Medical Plan B
group_id: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
id: 2705bb9f-3c90-4400-a4e7-0bc9d48e677c
version: 7a2b0437-4027-4251-9e71-85384c0eb1c9
schema:
$ref: '#/components/schemas/UIGroupPlatformMappingResult'
description: Successful Response - Returns a platform mapping
summary: Get Platform Mapping - Platform Account Structure and Group Mapping
tags:
- Groups
components:
schemas:
EnrollmentsFromCarrier:
properties:
enabled:
default: false
description: Flag indicating if receiving data from the carrier is enabled
type: boolean
type: object
GroupMedicalPlanPublicResult:
properties:
carrier_id:
description: Unique identifier of the associated carrier in Noyo
format: uuid
readOnly: true
type: string
cobra_rules:
allOf:
- $ref: '#/components/schemas/GroupPlanCOBRARules'
description: COBRA rules for the group medical plan
code:
description: Plan code of the group medical plan
example: MP25
type: string
created:
description: The date the record was created
type: integer
dependent_child_age_limits:
description: List of all dependent child age limits configured for the group medical plan
items:
$ref: '#/components/schemas/GroupPlanDependentChildAgeLimit'
type: array
effective_end_date:
description: ISO-8601 date string for the effective end date of the record
example: '2018-12-31'
format: date
nullable: true
type: string
effective_start_date:
description: ISO-8601 date string for the effective start date of the record
example: '2018-01-01'
format: date
nullable: true
type: string
eligible_member_types:
description: Eligible member types for the group medical plan
example:
- all
items:
type: string
readOnly: true
type: array
group_enrollment_id:
description: Unique identifier of the associated group enrollment in the Noyo system
format: uuid
type: string
id:
description: Unique identifier of the record in Noyo
format: uuid
type: string
line_of_coverage:
description: Line of coverage for the group medical plan
readOnly: true
type: string
metal_tier:
description: Metal tier designation of the group medical plan
enum:
- platinum
- gold
- silver
- bronze
type: string
modified:
description: The date the record was last updated
type: integer
name:
description: Name of the group medical plan
example: Gold PPO 2500
type: string
network:
description: Network name of the plan designated by the carrier
example: Medical Select
type: string
plan_configuration:
description: Group plan configuration details
readOnly: true
type: object
plan_type:
description: Type of group medical plan
enum:
- hmo
- ppo
- epo
- pos
- hdhp
- hmp
type: string
status:
description: Status of the group medical plan
enum:
- pending
- active
- discontinued
type: string
termination_policy:
description: Termination policy for the group medical plan
enum:
- end_of_month
- last_work_date
- fifteenth_of_month
- first_of_following_month
- end_of_plan_year
type: string
version:
description: Current version of the record
format: uuid
type: string
waiting_periods:
description: Member waiting period details for the group medical plan
items:
description: Member waiting period details for the group medical plan
type: object
type: array
required:
- carrier_id
- cobra_rules
- created
- group_enrollment_id
- id
- line_of_coverage
- modified
- name
- plan_configuration
- status
- termination_policy
- version
- waiting_periods
type: object
x-field_order:
- id
- version
- group_enrollment_id
- carrier_id
- line_of_coverage
- name
- code
- effective_start_date
- effective_end_date
- plan_type
- network
- metal_tier
- status
- eligible_member_types
- waiting_periods
- termination_policy
- cobra_rules
- plan_configuration
- created
- modified
GroupLTDPlanPublicResult:
properties:
benefits:
allOf:
- $ref: '#/components/schemas/GroupLTDPlanBenefitsSnapshot'
description: Description of benefits for the group LTD plan
carrier_id:
description: Unique identifier of the associated carrier in Noyo
format: uuid
readOnly: true
type: string
code:
description: Plan code of the group LTD plan
example: LTD
type: string
created:
description: The date the record was created
type: integer
effective_end_date:
description: ISO-8601 date string for the effective end date of the record
example: '2018-12-31'
format: date
nullable: true
type: string
effective_start_date:
description: ISO-8601 date string for the effective start date of the record
example: '2018-01-01'
format: date
nullable: true
type: string
eligible_member_types:
description: List of member types eligible for the group LTD plan
items:
description: Member type eligible for the group LTD plan
enum:
- all
- employee
- child
- spouse
- domestic-partner
- employee-with-dependents
type: string
minItems: 1
type: array
group_enrollment_id:
description: Unique identifier of the associated group enrollment in the Noyo system
format: uuid
type: string
id:
description: Unique identifier of the record in Noyo
format: uuid
type: string
line_of_coverage:
description: Line of coverage for the group LTD plan
readOnly: true
type: string
modified:
description: The date the record was last updated
type: integer
name:
description: Name of the group LTD plan
example: Employee LTD
type: string
plan_configuration:
description: Group plan configuration details
readOnly: true
type: object
plan_type:
description: Type of group LTD plan
enum:
- basic
- voluntary
type: string
status:
description: Status of the group LTD plan
enum:
- pending
- active
- discontinued
type: string
termination_policy:
description: Termination policy for the group LTD plan
enum:
- end_of_month
- last_work_date
- fifteenth_of_month
- first_of_following_month
- end_of_plan_year
type: string
version:
description: Current version of the record
format: uuid
type: string
volume_rules:
description: Volume rules for the group LTD plan
type: object
waiting_periods:
description: Member waiting period details for the group LTD plan
items:
description: Member waiting period details for the group LTD plan
type: object
type: array
required:
- carrier_id
- created
- eligible_member_types
- group_enrollment_id
- id
- line_of_coverage
- modified
- name
- plan_configuration
- plan_type
- status
- termination_policy
- version
- volume_rules
- waiting_periods
type: object
x-field_order:
- id
- version
- group_enrollment_id
- carrier_id
- line_of_coverage
- name
- code
- plan_type
- effective_start_date
- effective_end_date
- status
- eligible_member_types
- waiting_periods
- termination_policy
- volume_rules
- benefits
- plan_configuration
- created
- modified
Address:
properties:
city:
description: City of the address
example: Bend
type: string
county:
description: County of the address
example: Deschutes
type: string
state:
description: State postal code of the address
enum:
- AL
- AK
- AZ
- AR
- CA
- CO
- CT
- DE
- DC
- FL
- GA
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MD
- MA
- MI
- MN
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- OH
- OK
- OR
- PA
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VA
- WA
- WV
- WI
- WY
- AS
- GU
- MH
- FM
- MP
- PW
- PR
- VI
- UM
example: OR
type: string
street_one:
description: Line one of the address
example: 339 Hickory Street
type: string
street_two:
description: Line two of the address
example: Apartment 5
type: string
zip_code:
description: Zip code of the address
example: '97701'
pattern: ^(\d{5})(?:-?)(\d{4})?$
type: string
required:
- city
- state
- street_one
- zip_code
type: object
x-field_order:
- street_one
- street_two
- city
- state
- zip_code
- county
Meta:
properties:
offset:
description: The offset of the first response record within the matching data set
format: int32
minimum: 0
readOnly: true
type: integer
page_num:
description: The page number of the response records within the overall data set (1-based integer)
format: int32
minimum: 1
readOnly: true
type: integer
page_size:
description: The maximum number of response records on each page of results
format: int32
minimum: 1
readOnly: true
type: integer
total_records:
description: The total number of records in the entire matching data set
format: int32
minimum: 0
readOnly: true
type: integer
required:
- offset
- page_num
- page_size
type: object
UIGroupMappableFieldsResult:
properties:
configurable_values:
items:
description: Possible values for a mappable field, from the carrier
readOnly: true
type: object
readOnly: true
type: array
mapped_field:
allOf:
- $ref: '#/components/schemas/UIMappedField'
readOnly: true
required:
- configurable_values
- mapped_field
type: object
x-field_order:
- mapped_field
- configurable_values
PaginatedUIGroupPlanResult:
properties:
meta:
allOf:
- $ref: '#/components/schemas/Meta'
description: Metadata associated with the response data
response:
description: List of group plan results
items:
$ref: '#/components/schemas/UIGroupPlanResult'
type: array
required:
- meta
- response
type: object
x-field_order:
- meta
- response
PublicGroupCarrierConnectionConfigurationResult:
properties:
connection_tier:
description: Connection tier for the group
enum:
- premier
- advanced
- standard
- not_connected
nullable: true
type: string
data_exchange:
allOf:
- $ref: '#/components/schemas/DataExchange'
description: Data exchange configuration
nullable: true
type: object
PlatformAccountStructureAccountStructure:
properties:
account_structure_fields:
items:
$ref: '#/components/schemas/PlatformAccountStructureAccountStructureField'
type: array
plans:
allOf:
- $ref: '#/components/schemas/PlatformAccountStructureAccountStructurePlan'
description: Plans available for plan mapping
type: object
x-field_order:
- field_name
- field_type
- existing_value_set
PublicGroupCarrierConfigurationResult:
properties:
carrier_group_id:
description: Unique identifier for
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/noyo/refs/heads/main/openapi/noyo-groups-api-openapi.yml