Nayya Benefits API
The Benefits API from Nayya — 4 operation(s) for benefits.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/nayya-benefits-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Accounts Benefits API
description: Accounts API
version: '0.1'
contact: {}
servers:
- url: https://integrate.nayya.com/accounts
description: Production
- url: https://integrate.partners.nayya.com/accounts
description: Partners
security:
- bearerAuth: []
tags:
- name: Benefits
paths:
/employers/{employerId}/benefits/{benefitId}:
get:
operationId: get-benefit-by-id
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: benefitId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents a benefit (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitResponseDto'
'403':
description: Forbidden
'404':
description: Benefit Not Found
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal server error
summary: Get a Benefit by ID
tags:
- Benefits
delete:
operationId: delete-benefit-by-id
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: benefitId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents a benefit (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
responses:
'204':
description: No Content
'403':
description: Forbidden
'404':
description: Benefit Not Found
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal server error
summary: Delete a Benefit by ID
tags:
- Benefits
/employers/{employerId}/benefits:
get:
description: Response includes an array with the page and number of results requested. Results are returned in ascending order by `createdAt` date.
operationId: list-benefits-for-employer
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: page
required: false
in: query
description: Specifies which page of results to retrieve.
schema:
minimum: 1
default: 1
example: 2
type: number
- name: perPage
required: false
in: query
description: Number of results per page.
schema:
minimum: 1
maximum: 100
default: 50
example: 25
type: number
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedBenefitsResponseDto'
'403':
description: Forbidden
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal server error
summary: List Benefits for Employer
tags:
- Benefits
post:
operationId: create-or-update-benefit
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOrUpdateChooseBenefitRequestDto'
responses:
'201':
description: created
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitResponseDto'
'403':
description: Forbidden
'422':
description: Unprocessable entity
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal server error
summary: Create or Update a Benefit
tags:
- Benefits
/employers/{employerId}/benefits/employees/{employeeId}/enrolled-benefits:
get:
description: Response includes benefits that the employee is currently enrolled in.
operationId: list-enrolled-benefits-for-employee
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: employeeId
required: true
in: path
schema:
type: string
- name: page
required: false
in: query
description: Specifies which page of results to retrieve.
schema:
minimum: 1
default: 1
example: 2
type: number
- name: perPage
required: false
in: query
description: Number of results per page.
schema:
minimum: 1
maximum: 100
default: 50
example: 25
type: number
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedBenefitsResponseDto'
'403':
description: Forbidden
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal server error
summary: List Enrolled Benefits for Employee
tags:
- Benefits
/employers/{employerId}/benefits/{benefitId}/benefit-dependencies:
post:
operationId: add-benefit-dependencies-to-benefit
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: benefitId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents a benefit (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AddBenefitDependencyRequestDto'
responses:
'201':
description: created
content:
application/json:
schema:
$ref: '#/components/schemas/BenefitResponseDto'
'403':
description: Forbidden
'404':
description: Not Found
'422':
description: Unprocessable entity
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal server error
summary: Add Benefit Dependencies to Benefit
tags:
- Benefits
delete:
operationId: delete-benefit-dependencies-from-benefit
parameters:
- name: employerId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents an employer (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: benefitId
required: true
in: path
description: The unique ID from Nayya or your unique ID prefixed with the `external:` indicator that represents a benefit (e.g. `external:3438yht-hg8ht39-h23uh9th-uewht0o`).
schema:
type: string
- name: X-API-Version
in: header
required: false
description: Optional API major version. Omit this header for the same behavior as `1` (this specification).
schema:
type: string
default: '1'
responses:
'204':
description: No Content
'403':
description: Forbidden
'404':
description: Benefit Not Found
'429':
description: Unable to resolve employer ID after maximum retry attempts. This may be because the employer is not yet available or due to temporary system issues. Please try again.
'500':
description: Internal Server Error
summary: Delete Benefit Dependencies from Benefit
tags:
- Benefits
components:
schemas:
PaginatedBenefitsResponseDto:
type: object
properties:
data:
description: Array of Benefits.
type: array
items:
$ref: '#/components/schemas/BenefitResponseDto'
currentPage:
type: number
description: Current page number.
totalCount:
type: number
description: Total number of Benefit records.
totalPages:
type: number
description: Total number of pages.
required:
- data
- currentPage
- totalCount
- totalPages
CreateTierRequestDto:
type: object
properties:
externalId:
type: string
example: tier456
description: Your internal unique ID used to identify a tier
networkId:
type:
- string
- 'null'
example: network123
description: Ribbon Network ID associated with the Benefit Tier
displayName:
type: string
example: In Network
description: Name of the tier that will be visible to employees
type:
type: string
enum:
- in_network
- out_of_network
- specialty
example: in_network
description: Type of Tier or network grouping present under a Benefit
required:
- externalId
- displayName
- type
LabelResponseDto:
type: object
properties:
id:
type: string
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
description: Nayya's ID of the label
type:
type: string
example: category
description: Type of the label
value:
type: string
example: primary-care
description: Value of the label
createdAt:
format: date-time
type: string
example: '2024-11-22T20:03:04.395Z'
description: When the label was created
updatedAt:
format: date-time
type: string
example: '2024-12-22T20:03:04.395Z'
description: When the label was last updated
required:
- id
- type
- value
- createdAt
- updatedAt
TierResponseDto:
type: object
properties:
id:
type: string
example: d9428888-122b-11e1-b85c-61cd3cbb3210
description: Nayya's ID of the tier
externalId:
type: string
example: tier456
description: Your internal unique ID used to identify a tier
networkId:
type:
- string
- 'null'
example: network123
description: Ribbon Network ID associated with the Benefit Tier
displayName:
type: string
example: In Network
description: Name of the tier that will be visible to employees
type:
type: string
enum:
- in_network
- out_of_network
- specialty
example: in_network
description: Type of Tier or network grouping present under a Benefit
createdAt:
format: date-time
type: string
example: '2024-11-22T20:03:04.395Z'
description: when the tier was created
updatedAt:
format: date-time
type: string
example: '2024-12-22T20:03:04.395Z'
description: when the tier was last updated
required:
- id
- externalId
- displayName
- type
- createdAt
- updatedAt
CreateOrUpdateChooseBenefitRequestDto:
type: object
properties:
id:
type:
- string
- 'null'
example: 123e4567-e89b-12d3-a456-426614174000
description: Unique ID from Nayya used to identify a benefit
externalId:
type:
- string
- 'null'
example: 6937yht-zr5ht39-n83uh5th-arwmte1
description: Your internal unique ID used to identify a benefit
carrierId:
type: string
example: 6592a62b-297b-459b-954b-7e4941095149
description: Unique identifier for the carrier for this benefit
externalCarrierName:
type:
- string
- 'null'
example: Carrier 123
description: Name of the carrier for this benefit
description:
type:
- string
- 'null'
example: This benefit is a medical plan
description: Description of the benefit
type:
type: string
enum:
- medical
- dental
- vision
- short_term_disability
- long_term_disability
- accident
- hospital_indemnity
- critical_illness
- term_life
- whole_life
- universal_life
- basic_life
- pet_insurance
- pet_wellness
- accidental_death_and_dismemberment
- cancer
- identity_theft
- legal
- 401k
- 403b
- 457b
- HSA
- HRA
- FSA_medical
- limited_purpose_fsa
- dependent_care_fsa
- gap_insurance
- mental_health
- financial_wellness
- long_term_care
- telemedicine
- maternity
- diabetes
- chronic_joint_pain
- student_loan
- wellness
example: medical
description: Type of benefit
displayName:
type: string
example: Medical 1M Gold
description: Name of the benefit that will be visible to employees
activeAt:
format: date
type: string
example: '2020-01-01'
description: 'The start date for when the plan is effective in the format: YYYY-MM-DD'
inactiveAt:
format: date
type:
- string
- 'null'
example: '2020-12-31'
description: 'The end date for when the plan is no longer effective in the format: YYYY-MM-DD. This field does not need to be provided if a plan is anticipated to roll over from year to year'
detailsUrl:
type:
- string
- 'null'
example: https://example.com
description: URL to a benefit overview where an employee can see coverage details
code:
type:
- string
- 'null'
example: MEDICAL_GOLD_2024
description: Internal code used to identify this benefit
features:
type: array
items:
$ref: '#/components/schemas/CreateFeatureRequestDto'
tiers:
type: array
items:
$ref: '#/components/schemas/CreateTierRequestDto'
thresholds:
type: array
items:
$ref: '#/components/schemas/CreateThresholdRequestDto'
required:
- carrierId
- type
- displayName
- activeAt
- features
- tiers
- thresholds
CreateFeatureRequestDto:
type: object
properties:
id:
type:
- string
- 'null'
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
description: Nayya's internal ID for this Feature. This field can be provided to update an existing Feature by its internal ID.
displayName:
type: string
example: Office Visit
description: Name of the feature that will be visible to employees
type:
type: string
enum:
- office_visit
- specialist_visit
- inpatient
- outpatient
- diagnostic
- dental
- imaging
- emergency_care
- urgent_care
- telemedicine
- behavioral_health
- class_1_rx
- class_2_rx
- class_3_rx
- class_4_rx
- class_5_rx
- preventative_care
- basic_care
- major_care
- orthodontics
- child_orthodontics
- adult_orthodontics
- confinement
- portability
- short_term_disability
- long_term_disability
- heart_attack
- heart_condition
- cancer_major
- cancer_minor
- hospital_admission
- basic_life
- whole_life
- term_life
- universal_life
- employer_contribution
- frame_allowance
- annual_eye_exam
- employer_match
- therapies
- accidental_death_and_dismemberment
- adoption
- health_care_proxy
- traffic_matters
- debt_collection
- rollover
- maternity_coverage
- ambulance
- materials
- renal_failure
- organ_failure
- stroke
- health_screening
- mental_health_facility
- substance_abuse_facility
- nursing_facility
- air_ambulance
- catastrophic_loss
- common_carrier
- disaster
- concussion
- dental_treatment
- eye_surgery
- icu_admission
- icu_confinement
- physical_therapy
- prescribed_appliance
- prescribed_prosthetic
- rehabilitation_confinement
- single_vision_lenses
- bifocal_lenses
- trifocal_lenses
- polycarbonate_lenses
- progressive_lenses
- contact_lenses
- laser_vision_correction
- contact_lens_fitting
- additional_glasses
- guaranteed_issue
- spouse_guaranteed_issue
- spouse_term_life
- child_term_life
- critical_illness
example: office_visit
description: Type of Feature present under a Benefit
externalFeatureId:
type:
- string
- 'null'
example: feature123
description: Your unique internal ID used to identify this Feature. This field can be provided to update an existing Feature using your internal ID.
featureItems:
type: array
items:
$ref: '#/components/schemas/CreateEntityRuleRequestDto'
required:
- displayName
- featureItems
ThresholdItemResponseDto:
type: object
properties:
id:
type: string
example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
description: Nayya's ID of the threshold item
tierId:
type:
- string
- 'null'
example: 8c798fb8-b55d-475b-a4db-91786c0d58c7
description: Nayya's internal unique ID used to identify a tier
externalTierId:
type:
- string
- 'null'
example: tier456
description: Your internal unique ID used to identify a tier
ruleset:
description: Utilize a rule template with appropriate inputs
type: array
items:
$ref: '#/components/schemas/NayyaRulePropertiesDto'
createdAt:
format: date-time
type: string
example: '2024-11-22T20:03:04.395Z'
description: When the threshold item was created
updatedAt:
format: date-time
type: string
example: '2024-12-22T20:03:04.395Z'
description: When the threshold item was last updated
required:
- id
- createdAt
- updatedAt
FeatureResponseDto:
type: object
properties:
id:
type: string
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
description: Nayya's ID of the feature
displayName:
type: string
example: Office Visit
description: Name of the feature that will be visible to employees
createdAt:
format: date-time
type: string
example: '2024-11-22T20:03:04.395Z'
description: When the feature was created
updatedAt:
format: date-time
type: string
example: '2024-12-22T20:03:04.395Z'
description: When the feature was last updated
type:
type: string
enum:
- office_visit
- specialist_visit
- inpatient
- outpatient
- diagnostic
- dental
- imaging
- emergency_care
- urgent_care
- telemedicine
- behavioral_health
- class_1_rx
- class_2_rx
- class_3_rx
- class_4_rx
- class_5_rx
- preventative_care
- basic_care
- major_care
- orthodontics
- child_orthodontics
- adult_orthodontics
- confinement
- portability
- short_term_disability
- long_term_disability
- heart_attack
- heart_condition
- cancer_major
- cancer_minor
- hospital_admission
- basic_life
- whole_life
- term_life
- universal_life
- employer_contribution
- frame_allowance
- annual_eye_exam
- employer_match
- therapies
- accidental_death_and_dismemberment
- adoption
- health_care_proxy
- traffic_matters
- debt_collection
- rollover
- maternity_coverage
- ambulance
- materials
- renal_failure
- organ_failure
- stroke
- health_screening
- mental_health_facility
- substance_abuse_facility
- nursing_facility
- air_ambulance
- catastrophic_loss
- common_carrier
- disaster
- concussion
- dental_treatment
- eye_surgery
- icu_admission
- icu_confinement
- physical_therapy
- prescribed_appliance
- prescribed_prosthetic
- rehabilitation_confinement
- single_vision_lenses
- bifocal_lenses
- trifocal_lenses
- polycarbonate_lenses
- progressive_lenses
- contact_lenses
- laser_vision_correction
- contact_lens_fitting
- additional_glasses
- guaranteed_issue
- spouse_guaranteed_issue
- spouse_term_life
- child_term_life
- critical_illness
example: office_visit
description: Type of Feature present under a Benefit
featureItems:
type: array
items:
$ref: '#/components/schemas/FeatureItemResponseDto'
labels:
description: Labels associated with the feature
type: array
items:
$ref: '#/components/schemas/LabelResponseDto'
required:
- id
- displayName
- createdAt
- updatedAt
- type
- featureItems
AddBenefitDependencyRequestDto:
type: object
properties:
benefitDependencies:
type: array
items:
$ref: '#/components/schemas/CreateBenefitDependencyDto'
required:
- benefitDependencies
NayyaRulePropertiesDto:
type: object
properties:
conditions:
type: object
example:
any:
- fact: myFact
operator: equal
value: myValue
description: The conditions upon which emission of the corresponding event are predicated.
event:
type: object
example:
type: amount_per_day
params:
amount: 30
displayValue: $30 per day
description: The event emitted when predicate conditions are satisfied.
required:
- conditions
- event
BenefitDependencyResponseDto:
type: object
properties:
id:
type: string
example: 4e8392d4-f6b3-4cc0-9b77-b702f8115807
description: Nayya's ID of the benefit dependency
type:
type: string
enum:
- must_enroll_in
- must_enroll_in_one_of
- must_not_enroll_in
- must_not_enroll_in_one_of
example: must_enroll_in
description: Defines if enrollment is required or prohibited for the designated benefit based on the enrollment of another benefit
dependentBenefits:
example:
- 6937yht-zr5ht39-n83uh5th-arwmte1
- fs32231-zr5htDSA-n83uh5th-arwmte1
description: Comma-separated list of benefit ids affected by the dependency rule
type: array
items:
type: string
dependentBenefitsExternal:
example:
- 6937yht-zr5ht39-n83uh5th-arwmte1
- fs32231-zr5htDSA-n83uh5th-arwmte1
description: Comma-separated list of external benefit ids affected by the dependency rule
type: array
items:
type: string
createdAt:
format: date-time
type: string
example: '2024-11-22T20:03:04.395Z'
description: when the feature item was created
updatedAt:
format: date-time
type: string
example: '2024-12-22T20:03:04.395Z'
description: when the feature item was last updated
required:
- id
- type
- createdAt
- updatedAt
CreateBenefitDependencyDto:
type: object
properties:
type:
type: string
enum:
- must_enroll_in
- must_enroll_in_one_of
- must_not_enroll_in
- must_not_enroll_in_one_of
example: must_enroll_in
description: Defines the relationship of the dependency between the benefitID provided in the path and the parent benefit IDs provided in dependentBenefits or dependentBenefitsExternal
dependentBenefits:
example:
- 6937yht-zr5ht39-n83uh5th-arwmte1
- fs32231-zr5htDSA-n83uh5th-arwmte1
description: Comma-separated list of parent benefit IDs that the benefitID provided in the path will depend on. Either dependentBenefits or dependentBenefitsExternal must be provided
type: array
items:
type: string
dependentBenefitsExternal:
example:
- benefit-external-id-1
- benefit-external-id-2
description: Comma-separated list of parent benefit external IDs that the benefit provided in the path will depend on. Either dependentBenefits or dependentBenefitsExternal must be provided
type: array
items:
type: string
required:
- type
FeatureItemResponseDto:
type: object
properties:
id:
type: string
example: 8c798fb8-b55d-475b-a4db-91786c0d58c7
description: Nayya's ID of the feature item
name:
type:
- string
- 'null'
example: copay
description: Nayya's name of the feature item
tierId:
type:
- string
- 'null'
example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
description: Nayya's internal unique ID used to identify a tier
externalTierId:
type:
- string
- 'null'
example: tier123
description: Your internal unique ID used to identify a tier
ruleset:
description: A materialized rule belonging to the corresponding Feature
type: array
items:
$ref: '#/components/schemas/NayyaRulePropertiesDto'
createdAt:
format: date-time
type: string
example: '2024-11-22T20:03:04.395Z'
description: When the feature item was created
updatedAt:
format: date-time
type: string
example: '2024-12-22T20:03:04.395Z'
description: When the feature item was last updated
required:
- id
- createdAt
- updatedAt
CreateEntityRuleRequestDto:
type: object
properties:
id:
type:
- string
- 'null'
example: f47ac10b-58cc-4372-a567-0e02b2c3d479
description: Nayya's internal ID for this FeatureItem/ThresholdItem. This field can be provided to update an existing FeatureItem or ThresholdItem by its internal ID.
externalTierId:
type:
- string
- 'null'
example: tier456
description: Your internal unique ID used to
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/nayya/refs/heads/main/openapi/nayya-benefits-api-openapi.yml