Create an Employee

Creates an employee record under a company. This is the next step after creating a company.

Endpoint

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

Requires a bearer access token (see How to Get API Access). CLIENT_ID is the company identifier returned as id when you create the company.

Required fields:

Field	Type	Description
`firstName`	string	Employee's first name
`lastName`	string	Employee's last name
`ssn`	string	Social Security Number, with or without dashes
`birthDate`	string (ISO date)	Date of birth
`employeeType`	integer	See Employee Type values below

Employee Type values:

Value	Meaning
0	Employee
1	Contractor

These five fields are enough to create the employee record. To run payroll for this employee with no warnings or errors, also include hireDate, residentialAddress, contract (pay schedule and compensation).

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`;

const payload = {
  firstName: 'Michael',
  lastName: 'Brown',
  employeeType: 0, 
  ssn: '223-58-4084',
  birthDate: '1990-07-14T00:00:00.000Z',
  hireDate: '2026-09-11T00:00:00.000Z',
  residentialAddress: {
    addressLine1: '350 5th Ave',
    addressLine2: '',
    addressCity: 'NEW YORK',
    addressState: 'NY',
    addressZIP: '10118',
    addressCountry: 'US',
  },
  contract: {
    startOn: '2026-09-11T00:00:00.000Z',
    workSchedule: 2, 
    compensationType: 1,
    compensableHours: 40, 
    compensationAmount: 90000, 
    isStatutory: true,
    is943: false,
    workLocationId: 0, 
    socCode: '151252',
  },
  payAllocation: [
    {
      order: 1,
      payMethod: 2,
      allocatedBy: 2,
      amount: 100,
      accountHolderName: 'Michael Brown',
      accountType: 1,
      routingNumber: '123456780',
      accountNumber: '000123456791'
    }
  ],
};

async function createEmployee() {
  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)
  });

  console.log(response.status);
  const raw = await response.text();
  console.log(JSON.stringify(JSON.parse(raw), null, 2));
}

createEmployee();

curl -s -X POST "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" \
  -d '{
    "firstName": "Michael",
    "lastName": "Brown",
    "employeeType": 0,
    "ssn": "223-58-4084",
    "birthDate": "1990-07-14T00:00:00.000Z",
    "hireDate": "2026-09-11T00:00:00.000Z",
    "residentialAddress": {
      "addressLine1": "350 5th Ave",
      "addressLine2": "",
      "addressCity": "NEW YORK",
      "addressState": "NY",
      "addressZIP": "10118",
      "addressCountry": "US"
    },
    "contract": {
      "startOn": "2026-09-11T00:00:00.000Z",
      "workSchedule": 2,
      "compensationType": 1,
      "compensableHours": 40,
      "compensationAmount": 90000,
      "isStatutory": true,
      "is943": false,
      "workLocationId": 0,
      "socCode": "151252"
    },
    "payAllocation": [
      {
        "order": 1,
        "payMethod": 2,
        "allocatedBy": 2,
        "amount": 100,
        "accountHolderName": "Michael Brown",
        "accountType": 1,
        "routingNumber": "123456780",
        "accountNumber": "000123456791"
      }
    ]
  }' | jq .

import os
import json

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
CLIENT_ID = os.environ.get("CLIENT_ID")
URL = f"https://api.worklio.com/wep/companies/{CLIENT_ID}/employees"

payload = {
    "firstName": "Michael",
    "lastName": "Brown",
    "employeeType": 0,
    "ssn": "223-58-4084",
    "birthDate": "1990-07-14T00:00:00.000Z",
    "hireDate": "2026-09-11T00:00:00.000Z",
    "residentialAddress": {
        "addressLine1": "350 5th Ave",
        "addressLine2": "",
        "addressCity": "NEW YORK",
        "addressState": "NY",
        "addressZIP": "10118",
        "addressCountry": "US",
    },
    "contract": {
        "startOn": "2026-09-11T00:00:00.000Z",
        "workSchedule": 2,
        "compensationType": 1,
        "compensableHours": 40,
        "compensationAmount": 90000,
        "isStatutory": True,
        "is943": False,
        "workLocationId": 0,
        "socCode": "151252",
    },
    "payAllocation": [
        {
            "order": 1,
            "payMethod": 2,
            "allocatedBy": 2,
            "amount": 100,
            "accountHolderName": "Michael Brown",
            "accountType": 1,
            "routingNumber": "123456780",
            "accountNumber": "000123456791",
        }
    ],
}


def create_employee():
    response = requests.post(
        URL,
        headers={
            "accept": "application/json",
            "api-version": "2.0",
            "authorization": f"Bearer {TOKEN}",
            "content-type": "application/json",
            "x-api-version": "2.0",
        },
        json=payload,
    )

    print(response.status_code)

    raw = response.text
    print(json.dumps(json.loads(raw), indent=2))

    return response


if __name__ == "__main__":
    create_employee()

Example response

{
  "id": 4273,
  "firstName": "Michael",
  "lastName": "Brown",
  "middleName": "",
  "nickName": "",
  "employeeType": 0,
  "ssnMasked": "***-**-4084",
  "ssn": "223-58-4084",
  "birthDate": "1990-07-14",
  "hireDate": "2026-09-11",
  "email": "",
  "workEmail": "",
  "phone": "",
  "cellPhone": "",
  "workPhone": "",
  "workCellPhone": "",
  "residentialAddress": {
    "id": 5994,
    "addressLine1": "350 5th Ave",
    "addressLine2": "",
    "addressCity": "NEW YORK",
    "addressState": "NY",
    "addressZIP": "10118",
    "addressCountry": "US",
    "geoLatitude": 40.748217000,
    "geoLongitude": -73.985112000
  },
  "contract": {
    "id": 2975,
    "startOn": "2026-09-11",
    "workSchedule": 2,
    "compensationType": 1,
    "compensableHours": 40.0000,
    "compensationAmount": 90000.0000,
    "compensationNumberOfUnits": 0,
    "isStatutory": true,
    "is943": false,
    "workLocationId": 0,
    "wcCode": "0000",
    "socCode": "151252",
    "policyId": 1083,
    "payrollPolicyId": 1083,
    "toGroupId": 723,
    "payPeriod": 1,
    "status": 1
  },
  "payAllocation": [
    {
      "id": 1877,
      "order": 1,
      "payMethod": 2,
      "allocatedBy": 2,
      "amount": 100.0000,
      "accountNumber": "000123456791",
      "routingNumber": "123456780",
      "accountHolderName": "Michael Brown",
      "accountType": 1
    }
  ],
  "isAdmin": false,
  "employeeUI_ID": 1,
  "clockNumber": "",
  "country": "US",
  "workCountry": "US",
  "citizenshipCountry": "US",
  "citizenship": 1,
  "drivingLicenseCountry": "US",
  "bio": "",
  "eeo": {},
  "driverLicence": {
    "number": "",
    "class": "",
    "state": "  "
  },
  "w2Info": {
    "electronicOnly": false,
    "firstName": "Michael",
    "lastName": "Brown"
  },
  "jobDescription": "",
  "hrKeyDates": {
    "liabilityStart": "2026-09-08",
    "originalHire": "2026-09-08"
  }
}

{
  "status": 3,
  "code": "DataValidationError",
  "errorCode": "",
  "message": "One or more validation errors occurred.\r\nLastName: [requiredError:The field is required.]\r\nBirthDate: [requiredError:The field is required.]\r\nFirstName: [requiredError:The field is required.]\r\nEmployeeType: [requiredError:The field is required.]",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": {
    "lastName": [
      [
        "requiredError",
        "The field is required."
      ]
    ],
    "birthDate": [
      [
        "requiredError",
        "The field is required."
      ]
    ],
    "firstName": [
      [
        "requiredError",
        "The field is required."
      ]
    ],
    "employeeType": [
      [
        "requiredError",
        "The field is required."
      ]
    ]
  }
}

{
  "status": 0,
  "code": "400",
  "errorCode": "SSN_DuplicateError",
  "message": "9/11/2026 - 11:13:55 AM : Employee with the same SSN/FEIN already has an active employment with the current client.",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}

id is the employee's unique identifier — save it for later steps, like running payroll.

The full ssn is echoed back in the response; ssnMasked gives you a masked version (***-**-4084) if you need to display it without exposing the full number.

Pay allocation fields (payMethod, allocatedBy, accountType) are covered in more detail in the Pay Allocation guide.

Please save the id for later use.