> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.vitablehealth.com/api/employees/create-employee/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.vitablehealth.com/_mcp/server. # Create employee POST https://api.vitablehealth.com/v1/employers/{employer_id}/employees Content-Type: application/json 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. Reference: https://developer.vitablehealth.com/api/employees/create-employee ## Authentication - `Authorization` header (bearer token, required) — 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. ## Servers - `https://api.vitablehealth.com` (Production, default) - `https://api.uat.vitablehealth.com` (UAT) ## Request ### Path parameters - `employer_id` (string, required) — Unique employer identifier (empr_*) ### Headers - `X-Vitable-Organization` (string, optional) — 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`. ### Body (application/json) This endpoint expects a CreateEmployeeRequest. - `first_name` (string, required) — Employee's legal first name - `last_name` (string, required) — Employee's legal last name - `date_of_birth` (date, required) — Date of birth; the employee must be at least 18 - `email` (string, required) — Email for the employee's Vitable account. It cannot belong to another person. - `address` (EmployeeAddressInput, required) — Employee's residential address - `employee_class` (enum, required) — Employment classification * `Full Time` - Full Time * `Part Time` - Part Time * `Temporary` - Temporary * `Intern` - Intern * `Seasonal` - Seasonal * `Individual Contractor` - Individual Contractor - Allowed values: `Full Time`, `Part Time`, `Temporary`, `Intern`, `Seasonal`, `Individual Contractor` - `compensation_type` (enum, required) — Employee compensation type * `Salary` - Salary * `Hourly` - Hourly - Allowed values: `Salary`, `Hourly` - `start_date` (date, required) — Employment start date; must be on or before today in US Eastern time - `preferred_language` (enum, optional, nullable) — Preferred language code * `en` - English * `es` - Spanish * `zh` - Chinese * `ru` - Russian * `sw` - Swahili * `th` - Thai - Allowed values: `en`, `es`, `zh`, `ru`, `sw`, `th` - `middle_name` (string, optional, nullable) — Employee's legal middle name - `suffix` (enum, optional, nullable) — Name suffix * `Sr` - Sr * `Jr` - Jr * `I` - I * `II` - II * `III` - III * `IV` - IV * `V` - V - Allowed values: `Sr`, `Jr`, `I`, `II`, `III`, `IV`, `V` - `sex_at_birth` (enum, optional, nullable) — Sex assigned at birth * `Male` - Male * `Female` - Female * `Other` - Other * `Unknown` - Unknown - Allowed values: `Male`, `Female`, `Other`, `Unknown` - `phone` (string, optional, 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. ## Response ### 201 - `data` (Employee, required) — The employee record. ## Errors ### 400 Bad Request Error Invalid request. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 401 Unauthorized Error Unauthorized - Invalid or missing API key - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 403 Forbidden Error Forbidden - Insufficient permissions for this resource - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 404 Not Found Error Resource not found. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 409 Conflict Error Conflict with the current resource state. - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 422 Unprocessable Entity Error Unprocessable Entity - Business rule or domain invariant violated - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 429 Too Many Requests Error Too Many Requests - Rate limit exceeded - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 500 Internal Server Error Internal Server Error - An unexpected error occurred - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ### 502 Bad Gateway Error Bad Gateway - External service error - `timestamp` (datetime, required) — ISO 8601 timestamp when the error occurred - `message` (string, required) — Human-readable error message - `error` (string, required) — Error message (same as message, for backwards compatibility) - `trace_id` (string, required) — Unique trace ID for debugging and support requests - `app_error_code` (string, optional, nullable) — Application-specific error code for programmatic handling ## Types ### EmployeeAddressInput - `street_1` (string, required) — Primary street address - `city` (string, required) — City name - `state` (string, required) — Two-letter state code - `zip_code` (string, required) — ZIP code - `street_2` (string, optional, nullable) — Secondary street address - `country` (string, optional, default: US) — Country code. Only US addresses are supported; the value is ignored. ### Employee - `id` (string, required) — Unique employee identifier with 'empl_' prefix - `member_id` (string, required) — Unique member identifier with 'mbr_' prefix - `employer_id` (string, required) — Unique identifier of the employer this employment is with (empr_*) - `first_name` (string, required) — Employee's legal first name - `last_name` (string, required) — Employee's legal last name - `email` (string, required) — Email address - `date_of_birth` (date, required) — Date of birth (YYYY-MM-DD) - `phone` (string, required, nullable) — Phone number (10-digit US domestic string) - `employee_class` (enum, required) — Employment classification affecting benefit eligibility * `Full Time` - Full Time * `Part Time` - Part Time * `Temporary` - Temporary * `Intern` - Intern * `Seasonal` - Seasonal * `Individual Contractor` - Individual Contractor - Allowed values: `Full Time`, `Part Time`, `Temporary`, `Intern`, `Seasonal`, `Individual Contractor` - `status` (enum, required) — Employee status (active or terminated) - Allowed values: `active`, `terminated` - `start_date` (date, required) — Employee's start date with the employer - `classification_effective_date` (date, required) — Date the employee's current classification took effect - `compensation_type` (enum, required, nullable) — Employee's compensation type - Allowed values: `Salary`, `Hourly` - `compensation_type_effective_date` (date, required) — Date the employee's current compensation type took effect - `deductions` (list of DeductionDetail, required) — Payroll deductions from the most recent statement period. Replaced when a new statement is generated. - `created_at` (datetime, required) — Timestamp when the employee was created - `updated_at` (datetime, required) — Timestamp when the employee was last updated - `reference_id` (string, optional, nullable) — Partner-assigned reference ID for the employee - `employer_name` (string, optional, nullable) — Name of the employer this employment is with - `suffix` (string, optional, nullable) — Name suffix (e.g., Jr., Sr., III) - `gender` (string, optional, nullable) — Gender identity, if provided - `termination_date` (date, optional, nullable) — Employee's termination date, if terminated - `address` (EmployeeAddress, optional, nullable) — Employee's residential address ### DeductionDetail - `deduction_category` (string, required, nullable) — Deduction category (reserved for future use) - `deduction_amount_in_cents` (integer, required) — Employee deduction amount in cents - `tax_classification` (enum, required) — Tax classification: Pre-tax, Post-tax, or Unknown * `Unknown` - Unknown * `Pre-tax` - Pre Tax * `Post-tax` - Post Tax - Allowed values: `Unknown`, `Pre-tax`, `Post-tax` - `frequency` (enum, required) — Deduction frequency * `weekly` - Weekly * `bi_weekly` - Bi Weekly * `semi_monthly` - Semi Monthly * `monthly` - Monthly - Allowed values: `weekly`, `bi_weekly`, `semi_monthly`, `monthly` - `benefit_name` (string, required) — Name of the benefit plan - `period_start_date` (date, required) — Period start date (YYYY-MM-DD) - `period_end_date` (date, required) — Period end date (YYYY-MM-DD) ### EmployeeAddress - `address_line_1` (string, required) — Primary street address - `city` (string, required) — City name - `state` (string, required) — Two-letter state code (e.g., CA, NY) - `zipcode` (string, required) — ZIP code (5 or 9 digit) - `address_line_2` (string, optional, nullable) — Secondary street address (apt, suite, etc.) ## Examples **Request** ```json { "first_name": "John", "last_name": "Doe", "date_of_birth": "1985-06-15", "email": "john.doe@example.com", "address": { "street_1": "456 Oak Avenue", "city": "San Francisco", "state": "CA", "zip_code": "94102", "street_2": "Apt 2B" }, "employee_class": "Full Time", "compensation_type": "Salary", "start_date": "2023-01-15", "phone": "4155551234" } ``` **Response** ```json { "data": { "id": "string", "member_id": "string", "employer_id": "string", "first_name": "string", "last_name": "string", "email": "string", "date_of_birth": "2023-01-15", "phone": "string", "employee_class": "Full Time", "status": "active", "start_date": "2023-01-15", "classification_effective_date": "2023-01-15", "compensation_type": "Salary", "compensation_type_effective_date": "2023-01-15", "deductions": [ { "deduction_category": "string", "deduction_amount_in_cents": 1, "tax_classification": "Unknown", "frequency": "weekly", "benefit_name": "string", "period_start_date": "2023-01-15", "period_end_date": "2023-01-15" } ], "created_at": "2024-01-15T09:30:00Z", "updated_at": "2024-01-15T09:30:00Z", "reference_id": "string", "employer_name": "string", "suffix": "string", "gender": "string", "termination_date": "2023-01-15", "address": { "address_line_1": "string", "city": "string", "state": "string", "zipcode": "string", "address_line_2": "string" } } } ``` **SDK Code** ```python Create Employee import requests url = "https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees" payload = { "first_name": "John", "last_name": "Doe", "date_of_birth": "1985-06-15", "email": "john.doe@example.com", "address": { "street_1": "456 Oak Avenue", "city": "San Francisco", "state": "CA", "zip_code": "94102", "street_2": "Apt 2B" }, "employee_class": "Full Time", "compensation_type": "Salary", "start_date": "2023-01-15", "phone": "4155551234" } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Create Employee const url = 'https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"first_name":"John","last_name":"Doe","date_of_birth":"1985-06-15","email":"john.doe@example.com","address":{"street_1":"456 Oak Avenue","city":"San Francisco","state":"CA","zip_code":"94102","street_2":"Apt 2B"},"employee_class":"Full Time","compensation_type":"Salary","start_date":"2023-01-15","phone":"4155551234"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Create Employee package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees" payload := strings.NewReader("{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1985-06-15\",\n \"email\": \"john.doe@example.com\",\n \"address\": {\n \"street_1\": \"456 Oak Avenue\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip_code\": \"94102\",\n \"street_2\": \"Apt 2B\"\n },\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\",\n \"start_date\": \"2023-01-15\",\n \"phone\": \"4155551234\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Create Employee require 'uri' require 'net/http' url = URI("https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1985-06-15\",\n \"email\": \"john.doe@example.com\",\n \"address\": {\n \"street_1\": \"456 Oak Avenue\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip_code\": \"94102\",\n \"street_2\": \"Apt 2B\"\n },\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\",\n \"start_date\": \"2023-01-15\",\n \"phone\": \"4155551234\"\n}" response = http.request(request) puts response.read_body ``` ```java Create Employee import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1985-06-15\",\n \"email\": \"john.doe@example.com\",\n \"address\": {\n \"street_1\": \"456 Oak Avenue\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip_code\": \"94102\",\n \"street_2\": \"Apt 2B\"\n },\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\",\n \"start_date\": \"2023-01-15\",\n \"phone\": \"4155551234\"\n}") .asString(); ``` ```php Create Employee request('POST', 'https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees', [ 'body' => '{ "first_name": "John", "last_name": "Doe", "date_of_birth": "1985-06-15", "email": "john.doe@example.com", "address": { "street_1": "456 Oak Avenue", "city": "San Francisco", "state": "CA", "zip_code": "94102", "street_2": "Apt 2B" }, "employee_class": "Full Time", "compensation_type": "Salary", "start_date": "2023-01-15", "phone": "4155551234" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Create Employee using RestSharp; var client = new RestClient("https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1985-06-15\",\n \"email\": \"john.doe@example.com\",\n \"address\": {\n \"street_1\": \"456 Oak Avenue\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"zip_code\": \"94102\",\n \"street_2\": \"Apt 2B\"\n },\n \"employee_class\": \"Full Time\",\n \"compensation_type\": \"Salary\",\n \"start_date\": \"2023-01-15\",\n \"phone\": \"4155551234\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Create Employee import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "first_name": "John", "last_name": "Doe", "date_of_birth": "1985-06-15", "email": "john.doe@example.com", "address": [ "street_1": "456 Oak Avenue", "city": "San Francisco", "state": "CA", "zip_code": "94102", "street_2": "Apt 2B" ], "employee_class": "Full Time", "compensation_type": "Salary", "start_date": "2023-01-15", "phone": "4155551234" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.vitablehealth.com/v1/employers/empr_abc123def456/employees")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```