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

# Create a new employee

> Create a new employee record for a company.
This endpoint allows payroll providers to add new employees to the system
with complete demographic and employment information.




## OpenAPI

````yaml external-api-schema.yml post /v1/companies/{company_id}/employees
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/companies/{company_id}/employees:
    post:
      tags:
        - Company Members
      summary: Create a new employee
      description: >
        Create a new employee record for a company.

        This endpoint allows payroll providers to add new employees to the
        system

        with complete demographic and employment information.
      operationId: create_company_employee
      parameters:
        - in: path
          name: company_id
          schema:
            type: string
            format: uuid
          required: true
          description: Unique identifier for the company
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateCompanyEmployeeRequest'
      responses:
        '201':
          description: Employee created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateCompanyEmployeeResponse'
      security:
        - partnerApiKey: []
components:
  schemas:
    CreateCompanyEmployeeRequest:
      type: object
      properties:
        grant_benefit_eligibility_in:
          type: boolean
          description: Whether to grant benefit eligibility to the employee
        email:
          type: string
          format: email
          maxLength: 256
          description: Employee email address
        phone:
          type: string
          maxLength: 256
          description: Employee phone number
        first_name:
          type: string
          maxLength: 64
          description: Employee first name
        middle_name:
          type: string
          nullable: true
          maxLength: 200
          description: Employee middle name
        last_name:
          type: string
          maxLength: 64
          description: Employee last name
        suffix:
          type: string
          enum:
            - Sr
            - Jr
            - I
            - II
            - III
            - IV
            - V
          nullable: true
          description: Name suffix
        date_of_birth:
          type: string
          format: date
          description: Employee date of birth
        sex:
          type: string
          enum:
            - Male
            - Female
            - Other
            - Unknown
          description: Employee biological sex
        preferred_language:
          type: string
          enum:
            - en
            - es
            - zh
            - ru
            - sw
            - th
          description: Employee preferred language
        address:
          $ref: '#/components/schemas/CreateEmployeeAddress'
        employee_class:
          type: string
          enum:
            - Full Time
            - Part Time
            - Temporary
            - Intern
            - Seasonal
            - Individual Contractor
          description: Employment classification
        employee_start_date:
          type: string
          format: date
          description: Employee start date
        employee_compensation_type:
          type: string
          enum:
            - Salary
            - Hourly
          description: Compensation type
      required:
        - address
        - date_of_birth
        - email
        - employee_class
        - employee_compensation_type
        - employee_start_date
        - first_name
        - grant_benefit_eligibility_in
        - last_name
        - phone
    CreateCompanyEmployeeResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/CompanyMember'
    CreateEmployeeAddress:
      type: object
      properties:
        address_line_1:
          type: string
          description: First line of address
        address_line_2:
          type: string
          nullable: true
          description: Second line of address
        city:
          type: string
          description: City
        zipcode:
          type: string
          description: ZIP code
        state:
          type: string
          description: State abbreviation (e.g., CA, NY)
      required:
        - address_line_1
        - city
        - zipcode
        - state
    CompanyMember:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the company member
        hris_id:
          type: string
          nullable: true
          description: External HRIS identifier
        type:
          type: string
          enum:
            - Employee
            - Recruit
            - Youth
          description: Type of company member
        active_in:
          type: boolean
          description: Indicates whether this company member is active
        company_active_in:
          type: boolean
          description: Indicates whether the company is active
        employee_class:
          type: string
          enum:
            - Full Time
            - Part Time
            - Temporary
            - Intern
            - Seasonal
            - Individual Contractor
          nullable: true
          description: Employment classification
        employee_start_date:
          type: string
          format: date
          nullable: true
          description: Employee start date
        employee_compensation_type:
          type: string
          enum:
            - Salary
            - Hourly
          nullable: true
          description: Compensation type
        created:
          type: string
          format: date-time
          description: Record creation timestamp
        benefit_eligibility_start_date:
          type: string
          format: date-time
          nullable: true
          description: Date when benefit eligibility starts
        enrolled_in_benefits_in:
          type: boolean
          description: Whether enrolled in any active company benefits
        user_id:
          type: string
          format: uuid
          nullable: true
          description: Associated user ID
        member_id:
          type: string
          format: uuid
          description: Associated member ID
        address:
          $ref: '#/components/schemas/Address'
        address_str_format:
          type: string
          description: Formatted address string
        first_name:
          type: string
          description: Employee first name
        middle_name:
          type: string
          nullable: true
          description: Employee middle name
        last_name:
          type: string
          description: Employee last name
        full_name:
          type: string
          description: Employee full name
        suffix:
          type: string
          enum:
            - Sr
            - Jr
            - I
            - II
            - III
            - IV
            - V
          nullable: true
          description: Name suffix
        date_of_birth:
          type: string
          format: date
          description: Employee date of birth
        sex:
          type: string
          enum:
            - Male
            - Female
            - Other
            - Unknown
          nullable: true
          description: Employee biological sex
        gender:
          type: string
          enum:
            - Male
            - Female
            - Transgender
            - Non-binary
            - Prefer not to respond
          nullable: true
          description: Employee gender identity
        email:
          type: string
          nullable: true
          description: Employee email address
        phone_number:
          type: string
          nullable: true
          description: Employee phone number
        phone:
          type: string
          nullable: true
          description: Employee phone (alternative field)
        profile_picture_url:
          type: string
          nullable: true
          description: URL to profile picture
        preferred_language:
          type: string
          enum:
            - en
            - es
            - zh
            - ru
            - sw
            - th
          default: en
          description: Employee preferred language
        age:
          type: integer
          description: Employee age
        company_id:
          type: string
          format: uuid
          description: Company identifier
        public_company_id:
          type: string
          format: uuid
          description: Public company identifier
        company_name:
          type: string
          description: Company name
        individual_income_in_cents:
          type: integer
          description: Individual income in cents
        household_income_in_cents:
          type: integer
          description: Household income in cents
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
          description: Associated tags
      required:
        - address
        - address_str_format
        - age
        - benefit_eligibility_start_date
        - company_active_in
        - company_id
        - company_name
        - created
        - date_of_birth
        - email
        - enrolled_in_benefits_in
        - first_name
        - full_name
        - id
        - member_id
    Address:
      type: object
      properties:
        street_address:
          type: string
        city:
          type: string
        state:
          type: string
        zip_code:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the tag
        name:
          type: string
          description: Tag name
          maxLength: 256
        description:
          type: string
          nullable: true
          description: Tag description
          maxLength: 1024
        tag_color:
          type: string
          description: Tag color
          maxLength: 7
      required:
        - id
        - name
        - tag_color
  securitySchemes:
    partnerApiKey:
      type: apiKey
      in: header
      name: X-Partner-API-Key
      description: Partner API key for external integrations

````