Nayya Enrollments API

openapi: 3.0.0
info:
  title: Accounts Benefits Enrollments 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: Enrollments
paths:
  /employers/{employerId}/enrollments:
    post:
      description: Create one or more enrollments for a single employee in one request. All enrollments are created atomically - if one fails, all fail and are rolled back.
      operationId: create-enrollments
      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/CreateEnrollmentsRequestDto'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EnrollmentResponseDto'
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
      summary: Create Enrollments
      tags:
      - Enrollments
    get:
      description: List Enrollments of an Employee
      operationId: get-paginated-enrollments-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: query
        description: The ID of the employee to get enrollments for
        schema:
          format: uuid
          example: 123e4567-e89b-12d3-a456-426614174000
          type: string
      - name: page
        required: false
        in: query
        description: Page number (1-based).
        schema:
          minimum: 1
          default: 1
          example: 1
          type: number
      - name: perPage
        required: false
        in: query
        description: Number of results per page (max 100).
        schema:
          minimum: 1
          maximum: 100
          default: 50
          example: 50
          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: The enrollments for the given employee
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnrollmentsResponseDto'
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
      summary: List Enrollments of an Employee
      tags:
      - Enrollments
  /employers/{employerId}/enrollment:
    put:
      operationId: update-enrollment
      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/UpdateEnrollmentRequestDto'
      responses:
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
      summary: Update Enrollment
      tags:
      - Enrollments
    delete:
      operationId: delete-enrollment
      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/DeleteEnrollmentRequestDto'
      responses:
        '204':
          description: No Content
        '403':
          description: Forbidden
        '422':
          description: Unprocessable entity
        '500':
          description: Internal server error
      summary: Delete Enrollment
      tags:
      - Enrollments
components:
  schemas:
    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
          nullable: true
          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
    CreateEnrollmentsRequestDto:
      type: object
      properties:
        employeeId:
          type: string
          description: The ID of the employee being enrolled. Can be your id or Nayya's. All enrollments in this request will be for this employee. One of employeeId or employeeExternalId must be provided.
          example: 987e6543-e89b-12d3-a456-426614174000
        employeeExternalId:
          type: string
          description: The external ID of the employee being enrolled. All enrollments in this request will be for this employee. One of employeeId or employeeExternalId must be provided.
          example: EMP123456
        enrollments:
          description: Array of benefit enrollments to create for the employee specified above.
          example:
          - benefitId: 123e4567-e89b-12d3-a456-426614174000
            benefitAmountCents: 100000
            rateAmountCents: 5000
            beginsAt: '2024-01-01T00:00:00.000Z'
            groupNumber: GRP123456
          - benefitId: 223e4567-e89b-12d3-a456-426614174000
            dependentId: 567e8901-e89b-12d3-a456-426614174000
            benefitAmountCents: 50000
            rateAmountCents: 2500
            beginsAt: '2024-01-01T00:00:00.000Z'
            groupNumber: GRP123456
          type: array
          items:
            $ref: '#/components/schemas/CreateEnrollmentItemDto'
      required:
      - enrollments
    BenefitResponseDto:
      type: object
      properties:
        id:
          type: string
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          description: Nayya's ID of the benefit
        employerId:
          type: string
          example: 38a52be4-9352-453e-af97-5c3b448652b0
          description: Nayya's ID of the employer
        externalId:
          type: string
          nullable: true
          example: 6937yht-zr5ht39-n83uh5th-arwmte1
          description: Your internal unique ID used to identify a benefit
        externalCarrierName:
          type: string
          nullable: true
          example: Carrier 123
          description: Name of the carrier for this benefit
        carrierId:
          type: string
          example: 6592a62b-297b-459b-954b-7e4941095149
          description: Unique identifier for the carrier for this benefit
        type:
          type: string
          example: medical
          description: Type of benefit
          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
        displayName:
          type: string
          example: Medical 1M Gold
          description: Name of the benefit that will be visible to employees
        description:
          type: string
          nullable: true
          example: This benefit is a medical plan
          description: Description of the benefit
        activeAt:
          format: date-time
          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-time
          type: string
          nullable: true
          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
          nullable: true
          example: https://example.com
          description: URL to a benefit overview where an employee can see coverage details
        code:
          type: string
          nullable: true
          example: MEDICAL_GOLD_2024
          description: Internal code used to identify this benefit
        createdAt:
          format: date-time
          type: string
          example: '2024-11-22T20:03:04.395Z'
          description: When the benefit was created
        updatedAt:
          format: date-time
          type: string
          example: '2024-12-22T20:03:04.395Z'
          description: When the benefit was last updated
        features:
          type: array
          items:
            $ref: '#/components/schemas/FeatureResponseDto'
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/TierResponseDto'
        thresholds:
          type: array
          items:
            $ref: '#/components/schemas/ThresholdResponseDto'
        benefitDependencies:
          type: array
          items:
            $ref: '#/components/schemas/BenefitDependencyResponseDto'
      required:
      - id
      - employerId
      - externalId
      - carrierId
      - type
      - displayName
      - activeAt
      - createdAt
      - updatedAt
    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
    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
    EnrollmentResponseDto:
      type: object
      properties:
        id:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Nayya's ID of the enrollment
        benefitId:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Nayya's ID of the benefit
        benefit:
          description: Full benefit (features, thresholds, tiers, dependencies) for this enrollment
          allOf:
          - $ref: '#/components/schemas/BenefitResponseDto'
        employeeId:
          type: string
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Nayya's ID of the employee
        dependentId:
          type: object
          example: 123e4567-e89b-12d3-a456-426614174000
          description: Nayya's ID of the dependent
        benefitAmountCents:
          type: object
          example: 100000
          description: The benefit amount in cents
        rateAmountCents:
          type: object
          example: 100000
          description: The rate amount in cents
        beginsAt:
          format: date-time
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: The date the enrollment begins
        endsAt:
          type: object
          example: '2024-01-01T00:00:00.000Z'
          description: The date the enrollment ends
        groupNumber:
          type: object
          example: 123e4567-e89b-12d3-a456-426614174000
          description: The group number for the enrollment
        memberId:
          type: object
          example: 123e4567-e89b-12d3-a456-426614174000
          description: The member ID for the enrollment
        deductiblePayerCode:
          type: string
          description: The deductible payer code for this enrollment
          nullable: true
          example: AETNA123
        externalRelationship:
          type: string
          description: External relationship for enrollment owner
          nullable: true
        createdAt:
          format: date-time
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: When the enrollment was created
        updatedAt:
          format: date-time
          type: string
          example: '2024-01-01T00:00:00.000Z'
          description: When the enrollment was last updated
      required:
      - id
      - benefitId
      - employeeId
      - beginsAt
      - createdAt
      - updatedAt
    DeleteEnrollmentRequestDto:
      type: object
      properties:
        benefitId:
          type: string
          description: The ID of the benefit being enrolled in
          example: 123e4567-e89b-12d3-a456-426614174000
        employeeId:
          type: string
          description: The ID of the employee enrolling. One of employeeId or employeeExternalId must be provided.
          example: 123e4567-e89b-12d3-a456-426614174000
        employeeExternalId:
          type: string
          description: The external ID of the employee enrolling. One of employeeId or employeeExternalId must be provided.
          example: EMP123456
        dependentId:
          type: string
          description: The ID of the dependent being enrolled (if applicable)
          example: 123e4567-e89b-12d3-a456-426614174000
      required:
      - benefitId
    FeatureItemResponseDto:
      type: object
      properties:
        id:
          type: string
          example: 8c798fb8-b55d-475b-a4db-91786c0d58c7
          description: Nayya's ID of the feature item
        name:
          type: string
          example: copay
          description: Nayya's name of the feature item
          nullable: true
        tierId:
          type: string
          nullable: true
          example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
          description: Nayya's internal unique ID used to identify a tier
        externalTierId:
          type: string
          nullable: true
          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
    UpdateEnrollmentRequestDto:
      type: object
      properties:
        benefitId:
          type: string
          description: The ID of the benefit being enrolled in
          example: 123e4567-e89b-12d3-a456-426614174000
        employeeId:
          type: string
          description: The ID of the employee enrolling. One of employeeId or employeeExternalId must be provided.
          example: 123e4567-e89b-12d3-a456-426614174000
        employeeExternalId:
          type: string
          description: The external ID of the employee enrolling. One of employeeId or employeeExternalId must be provided.
          example: EMP123456
        dependentId:
          type: string
          description: The ID of the dependent being enrolled (if applicable)
          example: 123e4567-e89b-12d3-a456-426614174000
        benefitAmountCents:
          type: number
          description: The benefit amount in cents
          example: 100000
        rateAmountCents:
          type: number
          description: The rate amount in cents
          example: 5000
        beginsAt:
          format: date-time
          type: string
          description: When the enrollment begins
          example: '2024-01-01T00:00:00.000Z'
        endsAt:
          format: date-time
          type: string
          description: When the enrollment ends (if applicable)
          example: '2024-12-31T23:59:59.999Z'
        groupNumber:
          type: string
          description: The group number for the enrollment (if applicable)
          example: GRP123456
        memberId:
          type: string
          description: The member ID for the enrollment (if applicable)
          example: MEM123456
        deductiblePayerCode:
          type: string
          description: The deductible payer code for this enrollment (if applicable)
          example: AETNA123
          nullable: true
        externalRelationship:
          type: string
          description: External relationship for enrollment owner
          example: spouse
          nullable: true
      required:
      - benefitId
    ThresholdResponseDto:
      type: object
      properties:
        id:
          type: string
          example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
          description: Nayya's ID of the threshold
        displayName:
          type: string
          example: Individual Deductible
          description: Name of the threshold that will be visible to employees
        type:
          type: string
          enum:
          - deductible
          - out_of_pocket_max
          - embedded_deductible
          - family_deductible
          - family_out_of_pocket_max
          - weekly_benefit_max
          - monthly_benefit_max
          - annual_benefit_max
          - benefit_max
          - contribution_max
          - family_contribution_max
          - child_lifetime_orthodontia_max
          - adult_lifetime_orthodontia_max
          example: deductible
          description: Type of Threshold or financial boundary present under a Benefit
        createdAt:
          format: date-time
          type: string
          example: '2024-11-22T20:03:04.395Z'
          description: when the threshold was created
        updatedAt:
          format: date-time
          type: string
          example: '2024-12-22T20:03:04.395Z'
          description: When the threshold was last updated
        thresholdItems:
          type: array
          items:
            $ref: '#/components/schemas/ThresholdItemResponseDto'
      required:
      - id
      - displayName
      - type
      - createdAt
      - updatedAt
      - thresholdItems
    CreateEnrollmentItemDto:
      type: object
      properties:
        benefitId:
          type: string
          description: The ID of the benefit being enrolled in. Can you your id or Nayya's
          example: 123e4567-e89b-12d3-a456-426614174000
        dependentId:
          type: string
          description: The ID of the dependent being enrolled (if applicable). Can you your id or Nayya's
          example: 123e4567-e89b-12d3-a456-426614174000
        benefitAmountCents:
          type: number
          description: The benefit amount in cents
          example: 100000
        rateAmountCents:
          type: number
          description: The rate amount in cents
          example: 5000
        beginsAt:
          format: date-time
          type: string
          description: When the enrollment begins
          example: '2024-01-01T00:00:00.000Z'
        endsAt:
          type: string
          format: date-time
          description: When the enrollment ends (if applicable)
          example: '2024-12-31T23:59:59.999Z'
          nullable: true
        groupNumber:
          type: string
          description: The group number for the enrollment (if applicable)
          example: GRP123456
        memberId:
          type: string
          description: The member ID for the enrollment (if applicable)
          example: MEM123456
        deductiblePayerCode:
          type: string
          description: The deductible payer code for this enrollment (if applicable)
          example: AETNA123
          nullable: true
        externalRelationship:
          type: string
          description: External relationship for enrollment owner
          example: spouse
          nullable: true
      required:
      - benefitId
      - beginsAt
    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
    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
    PaginatedEnrollmentsResponseDto:
      type: object
      properties:
        data:
          description: Array of enrollments for the requested page.
          type: array
          items:
            $ref: '#/components/schemas/EnrollmentResponseDto'
        currentPage:
          type: number
          description: Current page number.
        totalCount:
          type: number
          description: Total number of enrollment records matching the query.
        totalPages:
          type: number
          description: Total number of pages.
      required:
      - data
      - currentPage
      - totalCount
      - totalPages
    ThresholdItemResponseDto:
      type: object
      properties:
        id:
          type: string
          example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
          description: Nayya's ID of the threshold item
        tierId:
          type: string
          nullable: true
          example: 8c798fb8-b55d-475b-a4db-91786c0d58c7
          description: Nayya's internal unique ID used to identify a tier
        externalTierId:
          type: string
          nullable: true
          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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token