Guides

    Company Basics

    Companies are the top-level entity in Worklio. Create one first, then use its id (referred to as CLIENT_ID in path parameters throughout this page) for later steps, such as creating employees.

    This page covers the company record's full lifecycle: creating a company, retrieving company data, updating an existing company, and blocking or unblocking a company.

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

    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 Payroll Policies to create one afterward.

    Endpoint

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

    Required fields:

    FieldDescription
    nameLegal name
    feinFederal EIN, with or without the dash
    companyTypeOne of the company type codes — see Company type below
    companyAddressaddressLine1, addressCity, addressState, addressZIP, addressCountry
    🚧

    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 incorrect tax configuration for the company.

    Company type

    companyType is an integer. These are the values Worklio accepts:

    ValueNameDescription
    1CorporationC-Corp
    2PartnershipPartnership
    3SCorpS-Corp
    4LLCPartnershipLLC Partnership
    5SoleProprietorshipSole Proprietor
    6LLCSoleProprietorLLC Sole Proprietor
    7LLCLLC C-Corp
    8LLCSCorpLLC S-Corp
    9NonProfitNon Profit
    10GovernmentalEntityGovernmental Entity

    Payroll policy (optional)

    Include payrollPolicy in the request to create a default payroll policy for the company at the same time. This becomes the company's DEFAULT payroll policy — you'll get its id back in the payrollPolicies array of the response.

    FieldDescription
    payFrequencyPay frequency, as an integer.
    firstPayPeriodEndDateEnd date of the first pay period.
    firstPayDateDate employees are paid for the first pay period.
    movePayDayOnHolidaysAndWeekends0 = move the pay day to after the holiday/weekend, 1 = move it to before.

    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, // Partnership
  fein: "123456789",
  tradeName: "Guide Company",
  startOn: "2027-09-01T00: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: "2027-09-10T00:00:00.000Z",
    firstPayDate: "2027-09-12T00: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);
  console.log(await response.text());
}

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": "2027-09-01T00: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": "2027-09-10T00:00:00.000Z",
      "firstPayDate": "2027-09-12T00:00:00.000Z",
      "movePayDayOnHolidaysAndWeekends": 1
    },
    "metaData": "sandbox test company",
    "enabledEWA": true,
    "enabledUnions": true
  }' | jq .

    Example response

    {
  "id": 1026,
  "name": "Guide Company",
  "fein": "123456789",
  "companyType": 2,
  "tradeName": "Guide Company",
  "startOn": "2027-09-01",
  "createdOn": "2026-09-11T09:06:53Z",
  "externalId": "sandbox-test-001",
  "website": "https://guidecompany.com",
  "phone": "+12125551234",
  "email": "[email protected]",
  "timeZone": 3,
  "companyAddress": {
    "id": 5984,
    "addressLine1": "233 S Wacker Drive",
    "addressLine2": "Suite 8400",
    "addressCity": "Chicago",
    "addressState": "IL",
    "addressZIP": "60606",
    "addressCountry": "US"
  },
  "payrollPolicy": {
    "payFrequency": 1,
    "firstPayPeriodEndDate": "2027-09-10",
    "firstPayDate": "2027-09-12",
    "movePayDayOnHolidaysAndWeekends": 1,
    "autoRun": false,
    "lastDayOfMonth": false
  },
  "payrollPolicies": [
    {
      "id": 1082,
      "companyId": 1026,
      "name": "DEFAULT",
      "frequency": 1,
      "autoRun": false,
      "initialSetup": {
        "payFrequency": 1,
        "firstPayPeriodEndDate": "2027-09-10",
        "firstPayDate": "2027-09-12",
        "movePayDayOnHolidaysAndWeekends": 1,
        "autoRun": false,
        "lastDayOfMonth": false
      }
    }
  ],
  "metaData": "sandbox test company",
  "reqEEJobCostCode": false,
  "enabledUnions": true,
  "enabledEWA": true,
  "blocked": false,
  "refCode": "wepL7156817",
  "uiNumber": 1054
}

    id is the company's unique identifier — save it for later steps, like creating employees under this company. This is the value used as CLIENT_ID in the path parameters below.

    If you included payrollPolicy in the request, the created policy also appears in payrollPolicies, named DEFAULT. Save payrollPolicies[0].id if you'll need to reference this policy later (for example, when running payroll).

    Time zone

    timeZone in the response identifies the company's local time zone. It's determined from companyAddress — this is another reason the address must be accurate. It can be set in a request.

    ValueNameDescription
    1PacificStandardTimePacific Standard Time
    2MountainStandardTimeMountain Standard Time
    3CentralStandardTimeCentral Standard Time
    4EasternStandardTimeEastern Standard Time
    5AlaskanStandardTimeAlaskan Standard Time
    6HawaiianStandardTimeHawaiian Standard Time
    7AtlanticStandardTimeAtlantic Standard Time
    8NewfoundlandStandardTimeNewfoundland Standard Time
    9USMountainStandardTimeUS Mountain Standard Time
    🚧

    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.

    Get Companies

    Worklio has three GET endpoints for retrieving company data: a basic list of every company visible to the current user, an admin-focused list with more operational fields, and a lookup for a single company's full detail.

    None of the three endpoints accept query parameters — there is no pagination, filtering, or sorting support. Each list endpoint always returns the full set of companies visible to the caller.

    List companies

    Returns a company for every company visible to the current user, using a minimal projection.

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

    Example request

    require("dotenv").config();

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

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

listCompanies();
    curl -s -X GET "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" | jq .

    Example response

    [
  {
    "id": 1029,
    "name": "Guide Company Test",
    "fein": "123456789",
    "status": 1,
    "uiNumber": 1057,
    "createdOn": "2026-09-11T11:51:16Z"
  },
  {
    "id": 1031,
    "name": "Guide Company REAL FINAL",
    "fein": "123456789",
    "status": 1,
    "uiNumber": 1059,
    "createdOn": "2026-09-11T12:19:00Z"
  },
  {
    "id": 1032,
    "name": "Milk Company",
    "fein": "123456789",
    "status": 1,
    "uiNumber": 1060,
    "createdOn": "2026-09-11T13:57:36Z"
  }
]

    List companies (admin projection)

    Returns the same set of companies as List companies above, but with a more administration-focused set of fields — pay schedule and processing-deadline info, contact details, and whether the company is blocked.

    GET https://api.worklio.com/wep/companies/list

    Example request

    require("dotenv").config();

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

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

listCompaniesAdmin();
    curl -s -X GET "https://api.worklio.com/wep/companies/list" \
  -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": 1029,
    "name": "Guide Company Test",
    "tradeName": "Guide Company",
    "fein": "123456789",
    "nextPayDate": "2026-09-11",
    "deadline": "2026-09-07T21:00:00Z",
    "daysForProcess": 4,
    "phoneNumber": "+12125551234",
    "email": "[email protected]",
    "blocked": false,
    "createdOn": "2026-09-11T11:51:16Z"
  },
  {
    "id": 1031,
    "name": "Guide Company REAL FINAL",
    "tradeName": "Guide Company",
    "fein": "123456789",
    "nextPayDate": "2026-09-11",
    "deadline": "2026-09-07T21:00:00Z",
    "daysForProcess": 4,
    "phoneNumber": "+12125551234",
    "email": "[email protected]",
    "blocked": false,
    "createdOn": "2026-09-11T12:19:00Z"
  },
  {
    "id": 1032,
    "name": "Milk Company",
    "tradeName": "Guide Company",
    "fein": "123456789",
    "nextPayDate": "2026-09-18",
    "deadline": "2026-09-14T21:00:00Z",
    "daysForProcess": 4,
    "phoneNumber": "+12125551234",
    "email": "[email protected]",
    "blocked": false,
    "createdOn": "2026-09-11T13:57:36Z"
  }
]

    Get a company

    Returns the full detail record for a single company.

    GET https://api.worklio.com/wep/companies/{CLIENT_ID}
    ParameterTypeRequiredDescription
    CLIENT_IDintegerYesThe company's id, as returned by List companies or List companies (admin projection). Path parameter.

    Example request

    require("dotenv").config();

const TOKEN = process.env.API_KEY;
const CLIENT_ID = 1031;
const url = `https://api.worklio.com/wep/companies/${CLIENT_ID}`;

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

getCompany();
    curl -s -X GET "https://api.worklio.com/wep/companies/1031" \
  -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": 1031,
  "name": "Guide Company REAL FINAL",
  "fein": "123456789",
  "companyType": 2,
  "tradeName": "Guide Company",
  "startOn": "2026-09-11",
  "businessSince": "2026-09-11",
  "createdOn": "2026-09-11T12:19:00Z",
  "externalId": "sandbox-test-001",
  "website": "https://guidecompany.com",
  "phone": "+12125551234",
  "email": "[email protected]",
  "timeZone": 3,
  "companyAddress": {
    "id": 6013,
    "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": 1087,
      "companyId": 1031,
      "name": "DEFAULT",
      "frequency": 1,
      "autoRun": false,
      "initialSetup": {
        "payFrequency": 1,
        "firstPayPeriodEndDate": "2026-09-11",
        "firstPayDate": "2026-09-11",
        "movePayDayOnHolidaysAndWeekends": 1,
        "autoRun": false,
        "lastDayOfMonth": false
      }
    },
    {
      "id": 1089,
      "companyId": 1031,
      "name": "newTestPayroll",
      "frequency": 1,
      "autoRun": false,
      "initialSetup": {
        "payFrequency": 1,
        "firstPayPeriodEndDate": "2026-09-10",
        "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": 1059
}

    Error response

    If CLIENT_ID doesn't exist, or isn't accessible to the current user, the endpoint returns:

    403 Access Denied

    Update a Company

    Updates an existing company's details. Use this to change information set at creation time — company name, contact info, address, and similar fields — without recreating the company.

    Endpoint

    PATCH https://api.worklio.com/wep/companies/{CLIENT_ID}
    ParameterTypeRequiredDescription
    CLIENT_IDintegerYesThe company's id, as returned by Create a Company or Get Companies. Path parameter.

    Content type

    This endpoint requires application/merge-patch+json, not application/json. Send only the fields you want to change — fields you omit keep their current value.

    content-type: application/merge-patch+json

    Fields

    All fields from Create a Company can be updated through this endpoint, except fein — see Updating fein below.

    FieldDescription
    nameLegal name
    tradeNameTrade / DBA name
    companyTypeOne of the company type codes — see Company type
    externalIdYour own reference id for the company
    emailCompany contact email
    websiteCompany website
    phoneCompany contact phone
    companyAddressaddressLine1, addressLine2, addressCity, addressState, addressZIP, addressCountry, geoLatitude, geoLongitude
    metaDataFree-text metadata field
    enabledEWAWhether earned wage access is enabled
    enabledUnionsWhether union support is enabled
    reqEEJobCostCodeWhether employees are required to have a job cost code
    startOnCompany start date. Accepted by this endpoint but not applied — see the note below.
    🚧

    companyAddress determines the company's tax jurisdiction — state and local tax setup is derived from it, and so is timeZone on the response. Changing it changes those downstream values too.

    🚧

    startOn and payrollPolicy are accepted but not applied. The request still returns 200 with no error, but the company's stored start date and payroll policy are left exactly as they were. A 200 response from this endpoint does not mean either field changed.

    Updating fein

    fein cannot be changed through this endpoint. Any request that includes fein — whether or not the value actually differs from what's stored — is rejected outright:

    {
  "status": 0,
  "code": "400",
  "errorCode": "FEINUpdateNotAllowed",
  "message": "9/15/2026 - 8:17:38 AM : Missing localization for key: Worklio.Business.WEP.Logic.CompanyLogic.FEINUpdateNotAllowed",
  "stackTrace": "",
  "pagination": {
    "pageNo": 0,
    "pageSize": 0,
    "totalRecords": 0,
    "totalPages": 0,
    "dataToken": ""
  },
  "validationErrors": null
}
    🚧

    The message text above ("Missing localization for key: ...") is what the API actually returns — it's a broken/untranslated error string, not a copy-paste mistake in this guide. Treat the HTTP 400 plus errorCode: "FEINUpdateNotAllowed" as the signal, not the message text.

    If you need to correct a company's FEIN, it can't be done through this endpoint.

    Example request

    This example updates Guide Company's name.

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

const payload = {
  name: "Guide Company PATCHED"
};

async function updateCompany() {
  const response = await fetch(url, {
    method: "PATCH",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "content-type": "application/merge-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));
}

updateCompany();
    curl -s -X PATCH "https://api.worklio.com/wep/companies/$CLIENT_ID" \
  -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 '{
    "name": "Guide Company PATCHED"
  }' | jq .

    Example response

    A successful update returns the full, updated company object — the same shape as Get a Company.

    {
  "id": 1031,
  "name": "Guide Company PATCHED",
  "fein": "123456789",
  "companyType": 2,
  "tradeName": "Guide Company",
  "startOn": "2026-09-11",
  "businessSince": "2026-09-11",
  "createdOn": "2026-09-11T12:19:00Z",
  "externalId": "sandbox-test-001",
  "website": "https://guidecompany.com",
  "phone": "+12125551234",
  "email": "[email protected]",
  "timeZone": 3,
  "companyAddress": {
    "id": 6013,
    "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": 1087,
      "companyId": 1031,
      "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": 1059
}

    Please save the returned object if you need to confirm what changed — the response reflects the company's full current state, not just the fields you sent.

    Block a Company

    Blocks a company and records why, using reason (plus customReason or state when the reason calls for it). The company's blocked field — already visible in the responses above — reflects this.

    Endpoint

    POST https://api.worklio.com/wep/companies/{CLIENT_ID}/block
    ParameterTypeRequiredDescription
    CLIENT_IDintegerYesThe company's id, as returned by Create a Company or Get Companies. Path parameter.
    content-type: application/json

    Fields

    FieldTypeRequiredDescription
    reasonint32 (enum)YesReason the company is being blocked. See Block reason below.
    customReasonstring | nullConditionalCustom reason. Valid only when reason is 5 (Other).
    statestring | nullConditionalTwo-letter state code (for example, IL). Valid only when reason is 2 (MissingStateTaxAccountInfo) or 3 (UnableToMakeFillingOrPayment).

    Block reason

    reason is an integer. These are the values Worklio accepts:

    ValueNameDescription
    1WaitingForAuthCompany authorization process was not completed
    2MissingStateTaxAccountInfoCertain state tax account information needed
    3UnableToMakeFillingOrPaymentUnable to make a filing or payment
    4NeededAdditionalDocOur team needs additional documentation
    5OtherOther reason

    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}/block`;

const payload = {
  reason: 2, // MissingStateTaxAccountInfo
  state: "IL"
};

async function blockCompany() {
  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);
  console.log(await response.text());
}

blockCompany();
    curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/block" \
  -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 '{
    "reason": 2,
    "state": "IL"
  }' | jq .

    Unblock a Company

    Unblocks a company. This is a separate endpoint from Block a Company — it takes no request body.

    Endpoint

    POST https://api.worklio.com/wep/companies/{CLIENT_ID}/unblock
    ParameterTypeRequiredDescription
    CLIENT_IDintegerYesThe company's id, as returned by Create a Company or Get Companies. Path parameter.

    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}/unblock`;

async function unblockCompany() {
  const response = await fetch(url, {
    method: "POST",
    headers: {
      accept: "application/json",
      "api-version": "2.0",
      authorization: `Bearer ${TOKEN}`,
      "x-api-version": "2.0"
    }
  });

  console.log(response.status);
  console.log(await response.text());
}

unblockCompany();
    curl -s -X POST "https://api.worklio.com/wep/companies/$CLIENT_ID/unblock" \
  -H "accept: application/json" \
  -H "api-version: 2.0" \
  -H "authorization: Bearer $API_KEY" \
  -H "x-api-version: 2.0" | jq .

    Updated 3 days ago

    Did this page help you?