Employee Basics

This page covers the everyday employee endpoints: list a company's employees, get a single employee, update an employee, and terminate an employee. To add an employee, see Create an Employee — creating an employee isn't repeated here.

All endpoints require a bearer access token (see How to Get API Access).

Endpoints overview

Method	Name	Endpoint
GET	List Employees	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees`
GET	Get an Employee	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}`
POST	Create an Employee	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees`
PATCH	Update an Employee	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}`
POST	Terminate an Employee	`https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/terminate`

Parameter	Type	Required	Description
`CLIENT_ID`	integer	Yes	The company's `id`, as returned by Create a Company or Get Companies. Path parameter.
`EMPLOYEE_ID`	integer	Yes	The employee's `id`, as returned by Create an Employee or List Employees. Path parameter. Not used by List Employees.

List Employees

Returns every employee and contractor of a company as a JSON array.

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/employees

This endpoint takes no request body.

Example request

require("dotenv").config();
 
const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees`;
 
async function listEmployees() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
  });
 
  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}
 
listEmployees();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/employees" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" | jq .

Example response

[
  {
    "id": 4328,
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "",
    "nickName": "",
    "employeeType": 0,
    "ssnMasked": "***-**-1184",
    "ssn": "223-58-1184",
    "email": "[email protected]",
    "workEmail": "",
    "phone": "",
    "cellPhone": "",
    "workPhone": "",
    "workCellPhone": "",
    "isAdmin": false,
    "status": 0,
    "employeeUI_ID": 16,
    "clockNumber": "",
    "hireDate": "2026-09-30T00:00:00Z",
    "country": "US",
    "citizenshipCountry": "US",
    "citizenship": 1,
    "drivingLicenseCountry": "US"
  },
  {
    "id": 4329,
    "firstName": "Sarah",
    "lastName": "Smith",
    "middleName": "",
    "nickName": "",
    "employeeType": 1,
    "ssnMasked": "***-**-4084",
    "ssn": "223-58-4084",
    "email": "[email protected]",
    "workEmail": "",
    "phone": "",
    "cellPhone": "",
    "workPhone": "",
    "workCellPhone": "",
    "isAdmin": false,
    "workSchedule": 2,
    "compensationType": 5,
    "status": 1,
    "employeeUI_ID": 17,
    "clockNumber": "",
    "payrollPolicyId": 1087,
    "policyId": 1087,
    "workFromHome": true,
    "hireDate": "2026-09-30T00:00:00Z",
    "country": "US",
    "citizenshipCountry": "US",
    "citizenship": 1,
    "drivingLicenseCountry": "US",
    "bio": "",
    "jobDescription": ""
  }
]

Notes on the response:

id is the employee's unique identifier. Use it as EMPLOYEE_ID in the other endpoints on this page and in later steps, such as running payroll.
employeeType is 0 for an employee and 1 for a contractor — see Create an Employee.
The full ssn is returned for every employee. ssnMasked (***-**-1184) is the masked version, for display.
workSchedule, compensationType, payrollPolicyId, policyId, workFromHome, bio, and jobDescription are returned only on some employees. In the example above they appear on the second employee and not on the first.

Employee status

Value	Name
0	`None`
1	`Active`
2	`Inactive`
3	`Terminated`
4	`LeaveOfAbsence`
5	`FMLA`
6	`SupervisorNotEmployed`
7	`OnCall`
8	`Pending`
9	`WorkCompLeave`
10	`RetireeWithPay`
11	`TerminationPending`

Work schedule

Value	Name
1	`PartTime`
2	`FullTime`
3	`Temporary`
4	`Intern`
5	`Seasonal`

Compensation type

Value	Name	Description
1	`Salaried`	Salaried
2	`Hourly`	Hourly
3	`Piecework`	Piecework
4	`Commissioned`	Commissioned
5	`Form1099`	1099 Employee
6	`OwnerDraws1099`	1099 - Owner Draws
7	`Tipped`	Tipped

Get an Employee

Returns the full record for a single employee.

GET https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}

This endpoint takes no request body.

Example request

This example gets employee 4328.

require("dotenv").config();
 
const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = 4328;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}`;
 
async function getEmployee() {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
  });
 
  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}
 
getEmployee();

curl -s -X GET "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/4328" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" | jq .

Example response

{
  "id": 4328,
  "firstName": "John",
  "lastName": "Doe",
  "middleName": "",
  "nickName": "",
  "employeeType": 0,
  "ssnMasked": "***-**-1184",
  "ssn": "223-58-1184",
  "hireDate": "2026-09-30",
  "email": "[email protected]",
  "workEmail": "",
  "phone": "",
  "cellPhone": "",
  "workPhone": "",
  "workCellPhone": "",
  "payAllocation": [
    {
      "id": 0,
      "order": 1,
      "payMethod": 1,
      "allocatedBy": 2,
      "amount": 100
    }
  ],
  "isAdmin": false,
  "employeeUI_ID": 16,
  "clockNumber": "",
  "country": "US",
  "citizenshipCountry": "US",
  "citizenship": 1,
  "drivingLicenseCountry": "US",
  "eeo": {},
  "driverLicence": {
    "number": "",
    "class": "",
    "state": "  "
  },
  "w2Info": {
    "electronicOnly": false,
    "firstName": "John",
    "lastName": "Doe"
  },
  "hrKeyDates": {
    "originalHire": "2026-09-30"
  }
}

The response has the same shape as the response to Create an Employee. It includes payAllocation, eeo, driverLicence, w2Info, and hrKeyDates, which List Employees doesn't return. Fields that were never set on the employee, such as birthDate, residentialAddress, and contract in the example above, are not returned.

Update an Employee

Updates an existing employee. Send only the fields you want to change.

PATCH https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}

The request body is a JSON object with the fields to change. The fields are the same ones you set when you create the employee.

Example request

This example changes employee 4328's firstName.

require("dotenv").config();
 
const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = 4328;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}`;
 
const payload = {
  firstName: "Johny"
};
 
async function updateEmployee() {
  const response = await fetch(url, {
    method: "PATCH",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/merege-patch+json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });
 
  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}
 
updateEmployee();

curl -s -X PATCH "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/4328" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/merge-patch+json" \
  -H "x-api-version: 2.0" \
  -d '{
    "firstName": "Johny"
  }' | jq .

Example response

A successful update returns the full, updated employee — the same shape as the response to Get an Employee, with the new values applied.

{
  "id": 4328,
  "firstName": "Johny",
  "lastName": "Doe",
  "middleName": "",
  "nickName": "",
  "employeeType": 0,
  "ssnMasked": "***-**-1184",
  "ssn": "223-58-1184",
  "hireDate": "2026-09-30",
  "email": "[email protected]",
  "workEmail": "",
  "phone": "",
  "cellPhone": "",
  "workPhone": "",
  "workCellPhone": "",
  "payAllocation": [
    {
      "id": 0,
      "order": 1,
      "payMethod": 1,
      "allocatedBy": 2,
      "amount": 100
    }
  ],
  "isAdmin": false,
  "employeeUI_ID": 16,
  "clockNumber": "",
  "country": "US",
  "citizenshipCountry": "US",
  "citizenship": 1,
  "drivingLicenseCountry": "US",
  "eeo": {},
  "driverLicence": {
    "number": "",
    "class": "",
    "state": "  "
  },
  "w2Info": {
    "electronicOnly": false,
    "firstName": "Johny",
    "lastName": "Doe"
  },
  "hrKeyDates": {
    "originalHire": "2026-09-30"
  }
}

Terminate an Employee

Terminates an employee as of a termination date.

POST https://api.worklio.com/wep/companies/{CLIENT_ID}/employees/{EMPLOYEE_ID}/terminate

Request fields

Only terminationDate is required. Every other field is optional.

Field	Type	Required	Description
`terminationDate`	string (date, `YYYY-MM-DD`)	Yes	The employee's termination date.
`terminationReason`	integer (enum)	No	Why the employee is being terminated. See Termination reason values.
`customTerminationReasonId`	integer \| null	Required when `terminationReason` is `200`	The id of the custom termination reason.
`timeOffRuleEndDate`	string (date, `YYYY-MM-DD`)	No	Date when time-off rule processing ends for the employee.
`netPayEndDate`	string (date, `YYYY-MM-DD`)	No	Date when net-pay processing ends for the employee.
`deductionCoverageEndDate`	integer (enum)	No	When deduction coverage ends. See Deduction coverage end date values.
`removeFromOrgChart`	boolean \| null	No	Set to `true` to remove the employee from the organization chart.

Termination reason values

Value	Name	Meaning
0	`NotSpecified`	Not specified
1	`NewOportunity`	New opportunity
2	`PersonalReasons`	Personal reasons
3	`ReturningToSchool`	Returning to school
101	`Restructure`	Restructure
102	`PositionElimination`	Position elimination
103	`Performance`	Performance
104	`Conduct`	Conduct
200	`Custom`	Custom — also send `customTerminationReasonId`
255	`ClientTermination`	Client termination

The name for value 1 is spelled NewOportunity in the API's enum.

Deduction coverage end date values

Value	Name	Meaning
0	`EndOfMonth`	Deduction coverage ends at the end of the month
1	`TerminationDate`	Deduction coverage ends on the termination date
2	`DefaultFromPlan`	Deduction coverage ends according to the benefit plan's default

Example request

This example terminates employee 4329 effective 2026-09-30, sending only the required field.

require("dotenv").config();
 
const TOKEN = process.env.API_KEY;
const CLIENT_ID = process.env.CLIENT_ID;
const EMPLOYEE_ID = 4329;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}/employees/${EMPLOYEE_ID}/terminate`;
 
const payload = {
  terminationDate: "2026-09-30"
};
 
async function terminateEmployee() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/json",
      "x-api-version": "2.0"
    },
    body: JSON.stringify(payload)
  });
 
  // A successful termination returns 204 with no body, so there is nothing to parse.
  console.log(response.status);
}
 
terminateEmployee();

curl -s -o /dev/null -w "%{http_code}\n" -X POST \
  "https://api.worklio.com/wep/companies/$CLIENT_ID/employees/4329/terminate" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "content-type: application/json" \
  -H "x-api-version: 2.0" \
  -d '{
    "terminationDate": "2026-09-30"
  }'

To set the optional fields, add them to the same request body. For example:

{
  "terminationDate": "2026-09-30",
  "terminationReason": 2,
  "timeOffRuleEndDate": "2026-09-30T00:00:00Z",
  "netPayEndDate": "2026-09-30T00:00:00Z",
  "deductionCoverageEndDate": 1,
  "removeFromOrgChart": true
}

Example response

204 No Content

A successful termination returns 204 with no response body. Don't parse the body of a 204 response as JSON.

Error responses

Terminating someone before their hire date results in an error.

{
  status: 0,
  code: '400',
  errorCode: 'TermDateIsBeforeAllEmp',
  message: '10/8/2026 - 9:12:13 AM : This employee cannot be terminated because there is no employment record for the selected date. This selected date may be before the initial hire date or the employee may have an employment set to start in the future.',
  stackTrace: '',
  pagination: {
    pageNo: 0,
    pageSize: 0,
    totalRecords: 0,
    totalPages: 0,
    dataToken: ''
  },
  validationErrors: null
}

Terminating someone who is already terminated without rehiring them before results in an error.

{
  status: 0,
  code: '400',
  errorCode: 'TermAlreadyTerminated',
  message: '10/8/2026 - 9:13:08 AM : A new Termination Date for this employee can only be set for a date that is after the Rehire Date.',
  stackTrace: '',
  pagination: {
    pageNo: 0,
    pageSize: 0,
    totalRecords: 0,
    totalPages: 0,
    dataToken: ''
  },
  validationErrors: null
}

Employee events — including Employee Created, Updated, and Terminated — are listed in Webhook Event Types.
To create several employees in one request, see Bulk Create Employees.

Endpoints overview

List Employees

Example request

Example response

Employee status

Work schedule

Compensation type

Get an Employee

Example request

Example response

Update an Employee

Example request

Example response

Terminate an Employee

Request fields

Termination reason values

Deduction coverage end date values

Example request

Example response

Error responses

Related