Create employee

client.employers.employees.create(, , ?): Employee { id, active, created_at, 7 more }

post/v1/employers/{employer_id}/employees

Creates a new employee for a specific employer. Requires personal information (name, DOB, SSN) and employment details (start date). Note: SSN can only be specified at creation time and cannot be updated later. Returns the created employee with assigned ID.

ParametersExpand Collapse

employerID: string

body: EmployeeCreateParams { date_of_birth, email, first_name, 9 more }

date_of_birth: string

Date of birth (YYYY-MM-DD)

formatdate

email: string

Email address

formatemail

first_name: string

Employee's legal first name

maxLength100

minLength1

last_name: string

Employee's legal last name

maxLength100

minLength1

sex: Sex

Male - Male
Female - Female
Other - Other
Unknown - Unknown

Accepts one of the following:

"Male"

"Female"

"Other"

"Unknown"

ssn: string

Social Security Number (XXX-XX-XXXX or XXXXXXXXX). Only accepted on create.

maxLength11

minLength9

start_date: string

Employment start/hire date

formatdate

address?: Address | null

Employee's residential address

city: string

City name

state: string

Two-letter state code

maxLength2

minLength2

street_1: string

Primary street address

zip_code: string

ZIP code

country?: string

Country code

street_2?: string | null

Secondary street address

employee_class?: EmployeeClass | null

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

Accepts one of the following:

"Full Time"

"Part Time"

"Temporary"

"Intern"

"Seasonal"

"Individual Contractor"

gender?: string | null

Gender identity

phone?: string | null

Phone number

suffix?: string | null

Name suffix (Jr., Sr., III)

maxLength10

ReturnsExpand Collapse

Employee { id, active, created_at, 7 more }

Serializer for Employee entity in public API responses.

Note: Employee is in the company module but exposed via account public API. Contains nested MemberEntity with personal identity information.

id: string

Unique employee identifier with 'empl_' prefix

active: boolean

Whether the employee is currently active

created_at: string

Timestamp when the employee was created

formatdate-time

employer_id: string

ID of the employer this employee works for (empr_*)

member: Member { id, date_of_birth, first_name, 6 more }

Nested member entity containing personal identity information.

Matches MemberEntity from account module domain.

id: string

Unique member identifier with 'mbr_' prefix

date_of_birth: string

Member's date of birth (YYYY-MM-DD)

formatdate

first_name: string

Member's legal first name

last_name: string

Member's legal last name

sex: Sex

Male - Male
Female - Female
Other - Other
Unknown - Unknown

Accepts one of the following:

"Male"

"Female"

"Other"

"Unknown"

email?: string | null

Email address for communications

formatemail

gender?: string | null

Gender identity, if provided

phone?: string | null

Phone number

suffix?: string | null

Name suffix (e.g., Jr., Sr., III)

start_date: string

Employee's start/hire date with the employer

formatdate

updated_at: string

Timestamp when the employee was last updated

formatdate-time

address?: Address | null

Nested address for employee.

city: string

City name

state: string

Two-letter state code

street_1: string

Primary street address

zip_code: string

ZIP code

country?: string

Country code

street_2?: string | null

Secondary street address

employee_class?: EmployeeClass | null

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

Accepts one of the following:

"Full Time"

"Part Time"

"Temporary"

"Intern"

"Seasonal"

"Individual Contractor"

termination_date?: string | null

Employee's termination date, if terminated

formatdate

Create employee

import VitableConnectAPI from 'vitable-connect-api';

const client = new VitableConnectAPI({
  apiKey: 'My API Key',
});

const employee = await client.employers.employees.create('empr_abc123def456', {
  date_of_birth: '2019-12-27',
  email: 'dev@stainless.com',
  first_name: 'x',
  last_name: 'x',
  sex: 'Male',
  ssn: 'xxxxxxxxx',
  start_date: '2019-12-27',
});

console.log(employee.id);

{
  "id": "id",
  "active": true,
  "created_at": "2019-12-27T18:11:19.117Z",
  "employer_id": "employer_id",
  "member": {
    "id": "id",
    "date_of_birth": "2019-12-27",
    "first_name": "first_name",
    "last_name": "last_name",
    "sex": "Male",
    "email": "dev@stainless.com",
    "gender": "gender",
    "phone": "phone",
    "suffix": "suffix"
  },
  "start_date": "2019-12-27",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "address": {
    "city": "city",
    "state": "state",
    "street_1": "street_1",
    "zip_code": "zip_code",
    "country": "country",
    "street_2": "street_2"
  },
  "employee_class": "Full Time",
  "termination_date": "2019-12-27"
}

Returns Examples

{
  "id": "id",
  "active": true,
  "created_at": "2019-12-27T18:11:19.117Z",
  "employer_id": "employer_id",
  "member": {
    "id": "id",
    "date_of_birth": "2019-12-27",
    "first_name": "first_name",
    "last_name": "last_name",
    "sex": "Male",
    "email": "dev@stainless.com",
    "gender": "gender",
    "phone": "phone",
    "suffix": "suffix"
  },
  "start_date": "2019-12-27",
  "updated_at": "2019-12-27T18:11:19.117Z",
  "address": {
    "city": "city",
    "state": "state",
    "street_1": "street_1",
    "zip_code": "zip_code",
    "country": "country",
    "street_2": "street_2"
  },
  "employee_class": "Full Time",
  "termination_date": "2019-12-27"
}