Skip to navigation
API ReferenceEmployees

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.

Authentication

AuthorizationBearer

API Key or Access Token authentication using Bearer token in Authorization header. API keys use the vit_apk_ prefix, access tokens use the vit_at_ prefix.

Path parameters

employer_idstringRequired

Unique employer identifier (empr_*)

Headers

X-Vitable-OrganizationstringOptional

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

This endpoint expects an object.
first_namestringRequired1-100 characters
Employee's legal first name
last_namestringRequired1-100 characters
Employee's legal last name
date_of_birthdateRequired

Date of birth; the employee must be at least 18

emailstringRequiredformat: "email"
Email for the employee's Vitable account. It cannot belong to another person.
addressobjectRequired
Employee's residential address
employee_classenumRequired

Employment classification

  • Full Time - Full Time
  • Part Time - Part Time
  • Temporary - Temporary
  • Intern - Intern
  • Seasonal - Seasonal
  • Individual Contractor - Individual Contractor
compensation_typeenumRequired

Employee compensation type

  • Salary - Salary
  • Hourly - Hourly
Allowed values:
start_datedateRequired

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

preferred_languageenum or nullOptional

Preferred language code

  • en - English
  • es - Spanish
  • zh - Chinese
  • ru - Russian
  • sw - Swahili
  • th - Thai
middle_namestring or nullOptional<=100 characters
Employee's legal middle name
suffixenum or nullOptional

Name suffix

  • Sr - Sr
  • Jr - Jr
  • I - I
  • II - II
  • III - III
  • IV - IV
  • V - V
sex_at_birthenum or nullOptional

Sex assigned at birth

  • Male - Male
  • Female - Female
  • Other - Other
  • Unknown - Unknown
Allowed values:
phonestring or nullOptional

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.

Response headers

X-RateLimit-Limitinteger
Maximum number of requests allowed within the rate limit window
X-RateLimit-Remaininginteger
Number of requests remaining in the current rate limit window
X-RateLimit-Resetinteger

Unix timestamp (seconds) when the rate limit window resets

Response

This endpoint returns an object.
dataobject
The employee record.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error