> ## Documentation Index
> Fetch the complete documentation index at: https://beta-docs.vitablehealth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Elect benefit enrollments

> Process benefit enrollment elections for employees and their dependents.
Allows payroll providers to submit enrollment choices, waive benefits,
add dependents, and complete the enrollment process with electronic signatures.




## OpenAPI

````yaml external-api-schema.yml post /v1/company-benefit-enrollments/elect
openapi: 3.0.3
info:
  title: Vitable External Partner API
  version: 1.0.0
  description: >
    External API for Payroll Providers and PEO platforms to integrate with
    Vitable health plan products 

    for benefit administration. This API enables partner systems to manage
    benefit enrollment, 

    employee data, and plan information for their clients.


    Common integration scenarios:

    - Retrieve active benefit plans for employers

    - List enrolled employees for benefit periods  

    - Create and update employee records

    - Manage benefit enrollments and elections

    - Access enrollment status and eligibility information
servers:
  - url: https://api.vitablehealth.com
    description: Production server
  - url: https://api-staging.vitablehealth.com
    description: Staging server
security:
  - partnerApiKey: []
tags:
  - name: Company Benefits
    description: Benefit plans available to companies (plan years)
  - name: Company Members
    description: Employee management and information
  - name: Benefit Enrollments
    description: Employee benefit enrollment status and management
  - name: Member Benefits
    description: Individual employee benefit information
  - name: Benefit Eligibility
    description: Employee benefit eligibility information
  - name: Payroll Integration
    description: Payroll deduction and contribution calculations
  - name: Quoting
    description: Marketplace plan searches and insurance quotes
paths:
  /v1/company-benefit-enrollments/elect:
    post:
      tags:
        - Enrollment Management
      summary: Elect benefit enrollments
      description: >
        Process benefit enrollment elections for employees and their dependents.

        Allows payroll providers to submit enrollment choices, waive benefits,

        add dependents, and complete the enrollment process with electronic
        signatures.
      operationId: elect_company_benefit_enrollments
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ElectCompanyBenefitEnrollmentsRequest'
      responses:
        '200':
          description: Enrollment elections processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ElectCompanyBenefitEnrollmentsResponse'
      security:
        - partnerApiKey: []
components:
  schemas:
    ElectCompanyBenefitEnrollmentsRequest:
      type: object
      properties:
        elections:
          type: array
          items:
            $ref: '#/components/schemas/ElectionRequest'
          description: Benefit election choices
        dependents:
          type: array
          items:
            $ref: '#/components/schemas/ElectionDependentRequest'
          description: Dependent information for enrollment
        signing:
          $ref: '#/components/schemas/ElectionSigningRequest'
          description: Electronic signature information
      required:
        - elections
        - dependents
        - signing
    ElectCompanyBenefitEnrollmentsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BenefitEnrollment'
          description: Processed enrollments
    ElectionRequest:
      type: object
      description: Benefit enrollment election request
      properties:
        enrollment_id:
          type: string
          format: uuid
          description: Unique enrollment identifier
        chosen_item_id:
          type: string
          format: uuid
          nullable: true
          description: Selected plan or option identifier
        chosen_external_plan:
          allOf:
            - $ref: '#/components/schemas/ExternalPlanData'
          nullable: true
          description: External plan selection data
        waived_dependents_fake_ids:
          type: array
          items:
            type: string
          description: List of dependents who waived coverage
        waived_in:
          type: boolean
          description: Whether coverage was waived
      required:
        - enrollment_id
        - waived_in
    ElectionDependentRequest:
      type: object
      description: Dependent information for benefit election
      properties:
        fake_id:
          type: string
          description: Temporary identifier for the dependent
        type:
          $ref: '#/components/schemas/BenefitDependentTypeEnum'
        first_name:
          type: string
          description: Dependent's first name
        last_name:
          type: string
          description: Dependent's last name
        suffix:
          allOf:
            - $ref: '#/components/schemas/NameSuffixEnum'
          nullable: true
          description: Name suffix
        date_of_birth:
          type: string
          format: date
          description: Dependent's date of birth
        email:
          type: string
          nullable: true
          description: Dependent's email address
        phone:
          type: string
          nullable: true
          description: Dependent's phone number
        address:
          allOf:
            - $ref: '#/components/schemas/Address'
          nullable: true
          description: Dependent's address
      required:
        - fake_id
        - type
        - first_name
        - last_name
        - date_of_birth
    ElectionSigningRequest:
      type: object
      properties:
        full_name:
          type: string
          description: Signer full name
        signature:
          type: string
          description: Electronic signature
        signature_date:
          type: string
          format: date
          description: Date of signature
        e_sign_consent_in:
          type: boolean
          description: Electronic signature consent
      required:
        - full_name
        - signature
        - signature_date
        - e_sign_consent_in
    BenefitEnrollment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique enrollment identifier
        company_benefit_id:
          type: string
          format: uuid
          description: Associated benefit plan ID
        company_member_id:
          type: string
          format: uuid
          description: Associated employee ID
        enrollment_status:
          type: string
          enum:
            - Unanswered
            - Enrolled
            - Waived
          description: Current enrollment status
        plan_name:
          type: string
          description: Selected benefit plan name
        tier_name:
          type: string
          description: Selected coverage tier
        employee_premium:
          type: integer
          description: Employee premium amount in cents
        employer_contribution:
          type: integer
          description: Employer contribution in cents
        coverage_start_date:
          type: string
          format: date
          description: Coverage effective date
        coverage_end_date:
          type: string
          format: date
          description: Coverage termination date
        enrollment_date:
          type: string
          format: date-time
          description: Date enrollment was completed
    ExternalPlanData:
      type: object
      description: External benefit plan information
      properties:
        plan_id:
          type: string
          description: External plan identifier
        plan_name:
          type: string
          description: External plan name
        carrier:
          type: string
          description: Insurance carrier name
      required:
        - plan_id
        - plan_name
    BenefitDependentTypeEnum:
      type: string
      enum:
        - spouse
        - child
        - domestic_partner
      description: Type of dependent relationship
    NameSuffixEnum:
      type: string
      enum:
        - Jr.
        - Sr.
        - II
        - III
        - IV
      description: Name suffix options
    Address:
      type: object
      properties:
        street_address:
          type: string
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
  securitySchemes:
    partnerApiKey:
      type: apiKey
      in: header
      name: X-Partner-API-Key
      description: Partner API key for external integrations

````