Employees

Create employee

Adds an employee to an employer. The caller must be authorized for the employer; an unknown or unauthorized employer returns 404, and so do credentials scoped to a single employee. A person who already exists in Vitable is linked to the employer rather than duplicated. Eligibility and enrollment are not immediate: they are recalculated periodically and can take a few hours to reflect a new employee.

409 app_error_code values: employer_has_hris_connection (an active, pending or inactive HRIS connection manages this roster; paused connections do not block), employer_has_no_active_subscription, and employee_already_exists (the person is already on this employer's roster, including former employees).

422 app_error_code values: email_taken (the email belongs to another person's Vitable account) and invalid_account_update (another account detail, such as the phone, belongs to another person).

400 is returned for malformed input and for data the employee record rejects (invalid_employee_update, the same code PATCH uses), such as an employee under 18 or a start date after today in US Eastern time.

post/v1/employers/{employer_id}/employees

Request

  • Base URL: https://api.vitablehealth.com
  • URL: https://api.vitablehealth.com/v1/employers/{employer_id}/employees
  • Auth: HTTP bearer

Path parameters

employer_idstring required

Unique employer identifier (empr_*)

Headers

X-Vitable-Organizationstring

Organization to act as for this request (e.g. org_SGVsbG8gV29ybGQ). Optional when your credentials reach a single organization. Required when they reach several — omitting it then returns 400 organization_required. A malformed value returns 400 invalid_organization_header, and naming an organization you do not have access to returns 403 organization_access_denied.

Request body

preferred_language'en' | 'es' | 'zh' | 'ru' | 'sw' | 'th'
  • en - English
  • es - Spanish
  • zh - Chinese
  • ru - Russian
  • sw - Swahili
  • th - Thai
first_namestring required

Employee's legal first name

middle_namestring nullable

Employee's legal middle name

last_namestring required

Employee's legal last name

suffix'Sr' | 'Jr' | 'I' | 'II' | 'III' | 'IV' | 'V'
  • Sr - Sr
  • Jr - Jr
  • I - I
  • II - II
  • III - III
  • IV - IV
  • V - V
sex_at_birth'Male' | 'Female' | 'Other' | 'Unknown'
  • Male - Male
  • Female - Female
  • Other - Other
  • Unknown - Unknown
date_of_birthstring date required

Date of birth; the employee must be at least 18

emailstring email required

Email for the employee's Vitable account. It cannot belong to another person.

phonestring nullable

10-digit US phone number; formatting characters and a leading 1 are ignored. Optional, as in the census sync, because partners do not always hold a phone for every employee.

employee_class'Full Time' | 'Part Time' | 'Temporary' | 'Intern' | 'Seasonal' | 'Individual Contractor' required
  • Full Time - Full Time
  • Part Time - Part Time
  • Temporary - Temporary
  • Intern - Intern
  • Seasonal - Seasonal
  • Individual Contractor - Individual Contractor
compensation_type'Salary' | 'Hourly' required
  • Salary - Salary
  • Hourly - Hourly
start_datestring date required

Employment start date; must be on or before today in US Eastern time

Response

Changes

No recorded changes to this operation across all 1 revision of this API.