Guides
  1. Quick Start

Create a Company

Creates a new company under your developer account. This is the next step after getting an access token — you'll need the company id returned by this call for later steps, such as creating employees.

You can also set up the company's default payroll policy in the same call, by including a payrollPolicy object in the request. If you skip it, the company is created with no payroll policy — see Company Basics to create one afterward. If you want to follow full quickstart guide create it with the company.

Endpoint

POST https://api.worklio.com/wep/companies

Requires a bearer access token (see How to Get API Access).

Required fields:

FieldDescription
nameLegal name
feinFederal EIN, with or without the dash
companyTypeSee the value below
companyAddressaddressLine1, addressCity, addressState, addressZIP, addressCountry

For the full field reference, all optional company fields, and edge-case behavior — see Create a Company under Company Onboarding

🚧

companyAddress must be a real, deliverable address. Worklio uses it to determine the company's tax jurisdiction — state and local tax setup is derived from this address — so a placeholder or fake address will produce error.

Example request

require("dotenv").config();

const TOKEN = process.env.API_KEY;
const url = "https://api.worklio.com/wep/companies";

const payload = {
  name: "Guide Company",
  companyType: 2,
  fein: "123456789",
  tradeName: "Guide Company",
  startOn: "2026-09-11T00:00:00.000Z",
  externalId: "sandbox-test-001",
  email: "[email protected]",
  website: "https://guidecompany.com",
  phone: "+12125551234",
  companyAddress: {
    addressLine1: "233 S Wacker Drive",
    addressLine2: "Suite 8400",
    addressCity: "Chicago",
    addressState: "IL",
    addressZIP: "60606",
    addressCountry: "US",
    geoLatitude: 41.8789,
    geoLongitude: -87.6359
  },
  payrollPolicy: {
    payFrequency: 1, // weekly
    firstPayPeriodEndDate: "2026-09-11T00:00:00.000Z",
    firstPayDate: "2026-09-11T00:00:00.000Z",
    movePayDayOnHolidaysAndWeekends: 1 // 0 = after, 1 = before
  },
  metaData: "sandbox test company",
  enabledEWA: true,
  enabledUnions: true
};

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

createCompany();
curl -s -X POST "https://api.worklio.com/wep/companies" \
  -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 '{
    "name": "Guide Company",
    "companyType": 2,
    "fein": "123456789",
    "tradeName": "Guide Company",
    "startOn": "2026-09-11T00:00:00.000Z",
    "externalId": "sandbox-test-001",
    "email": "[email protected]",
    "website": "https://guidecompany.com",
    "phone": "+12125551234",
    "companyAddress": {
      "addressLine1": "233 S Wacker Drive",
      "addressLine2": "Suite 8400",
      "addressCity": "Chicago",
      "addressState": "IL",
      "addressZIP": "60606",
      "addressCountry": "US",
      "geoLatitude": 41.8789,
      "geoLongitude": -87.6359
    },
    "payrollPolicy": {
      "payFrequency": 1,
      "firstPayPeriodEndDate": "2026-09-11T00:00:00.000Z",
      "firstPayDate": "2026-09-11T00:00:00.000Z",
      "movePayDayOnHolidaysAndWeekends": 1
    },
    "metaData": "sandbox test company",
    "enabledEWA": true,
    "enabledUnions": true
  }' | jq .
import os
import json

import requests
from dotenv import load_dotenv

load_dotenv()

TOKEN = os.environ.get("API_KEY")
URL = "https://api.worklio.com/wep/companies"

payload = {
    "name": "Guide Company",
    "companyType": 2,
    "fein": "123456789",
    "tradeName": "Guide Company",
    "startOn": "2026-09-11T00:00:00.000Z",
    "externalId": "sandbox-test-001",
    "email": "[email protected]",
    "website": "https://guidecompany.com",
    "phone": "+12125551234",
    "companyAddress": {
        "addressLine1": "233 S Wacker Drive",
        "addressLine2": "Suite 8400",
        "addressCity": "Chicago",
        "addressState": "IL",
        "addressZIP": "60606",
        "addressCountry": "US",
        "geoLatitude": 41.8789,
        "geoLongitude": -87.6359,
    },
    "payrollPolicy": {
        "payFrequency": 1,  # weekly
        "firstPayPeriodEndDate": "2026-09-11T00:00:00.000Z",
        "firstPayDate": "2026-09-11T00:00:00.000Z",
        "movePayDayOnHolidaysAndWeekends": 1,  # 0 = after, 1 = before
    },
    "metaData": "sandbox test company",
    "enabledEWA": True,
    "enabledUnions": True,
}


def create_company():
    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_company()

Example response

{
  "id": 1027,
  "name": "Guide Company",
  "fein": "123456789",
  "companyType": 2,
  "tradeName": "Guide Company",
  "startOn": "2026-09-11",
  "createdOn": "2026-09-11T09:06:53Z",
  "externalId": "sandbox-test-001",
  "website": "https://guidecompany.com",
  "phone": "+12125551234",
  "email": "[email protected]",
  "timeZone": 3,
  "companyAddress": {
    "id": 5988,
    "addressLine1": "233 S Wacker Drive",
    "addressLine2": "Suite 8400",
    "addressCity": "Chicago",
    "addressState": "IL",
    "addressZIP": "60606",
    "addressCountry": "US"
  },
  "payrollPolicy": {
    "payFrequency": 1,
    "firstPayPeriodEndDate": "2026-09-11",
    "firstPayDate": "2026-09-11",
    "movePayDayOnHolidaysAndWeekends": 1,
    "autoRun": false,
    "lastDayOfMonth": false
  },
  "payrollPolicies": [
    {
      "id": 1083,
      "companyId": 1027,
      "name": "DEFAULT",
      "frequency": 1,
      "autoRun": false,
      "initialSetup": {
        "payFrequency": 1,
        "firstPayPeriodEndDate": "2026-09-11",
        "firstPayDate": "2026-09-11",
        "movePayDayOnHolidaysAndWeekends": 1,
        "autoRun": false,
        "lastDayOfMonth": false
      }
    }
  ],
  "metaData": "sandbox test company",
  "reqEEJobCostCode": false,
  "enabledUnions": true,
  "enabledEWA": true,
  "blocked": false,
  "refCode": "wepL7156817",
  "uiNumber": 1054
}
{
  "status": 3,
  "code": "DataValidationError",
  "errorCode": "",
  "message": "One or more validation errors occurred.\r\nFEIN: [requiredError:The field is required.]\r\nName: [requiredError:The field is required.]\r\nCompanyType: [requiredError:The field is required.]\r\nCompanyAddress: [requiredError:The field is required.]",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": {
    "fein": [
      [
        "requiredError",
        "The field is required."
      ]
    ],
    "name": [
      [
        "requiredError",
        "The field is required."
      ]
    ],
    "companyType": [
      [
        "requiredError",
        "The field is required."
      ]
    ],
    "companyAddress": [
      [
        "requiredError",
        "The field is required."
      ]
    ]
  }
}

id is the company's unique identifier — save it for later steps, like creating employees under this company.

🚧

If you don't send startOn, Worklio sets it to the date the request was made — you don't need to set it just to get a runnable request going.

🚧

If you don't send payrollPolicy, the company is created with an empty payrollPolicies array. You can create a policy afterward — see Payroll Policies.

Please save the id for later use.

Updated 27 minutes ago

Did this page help you?