Set up a test environment

This guide will demonstrate how to create Companies, Workplaces, Employees, and Payrolls—the minimum necessary steps to pay a W2 employee.

Set up a test environment

Postman Collection

We are currently working on making a fully-featured Postman collection available.

1. Create a Company

The first step is to create a company, the employer paying their workers. Each company is a separate tax entity with a single Employer Identification Number (EIN). Your customer may own multiple companies under a single brand (e.g. Restaurants or franchises) or multiple companies under separate brands. Each company must be created separately but they can be associated with each other through a corporation entity in the EncompassFi API.

curl -X POST \ 
  https://sandbox.encompassfi.com/companies \
  -H 'Content-Type: application/json' \
  -H 'X-API-key: <API_KEY>' \
  -d '{
    "legalName": "Big Box Store Co.",
    "tradeName": "Big Box Store",
    "email": "[email protected]",
    "phone": "5555555555",
    "address": {
      "street1": "2450 St Rose Pkwy",
      "street2": "Suite 120",
      "city": "Henderson",
      "zipcode": "89074",
      "state": "NV",
      "country": "US"
    }
  }'

curl -i -X POST \
  'https://sandbox.encompassfi.com/companies/<companyId>/start_payroll' \
  -H 'Content-Type: application/json' \
  -d '{
    "startDate": "2019-08-24",
    "legalName": "string",
    "tradeName": "string",
    "email": "string",
    "phone": "string",
    "website": "string",
    "type": "LLC",
    "industry": "GeneralConstructionGeneralContracting",
    "payFrequency": "Weekly",
    "employeeW2DeliveryMethod": "PrintAndMailAll",
    "contractor1099DeliveryMethod": "PrintAndMailAll"
  }'

2. Create a Workplace

The next step is to create a workplace. EncompassFi needs to know the physical location where the employee does their work. This can be a office location or the employee's residential address (if they work from home). Workplace address is ofter the same as the company address but many companies are registered at a different location than their workers work from. Companies can have multiple workplaces in multiple states.

curl -X POST \ 
  https://sandbox.encompassfi.com/companies/<companyId>/workplaces \
  -H 'Content-Type: application/json' \
  -H 'X-API-key: <API_KEY>' \
  -d '{
    "name": "Henderson Office",
    "active": true,
    "address": {
      "street1": "2450 St Rose Pkwy",
      "street2": "Suite 120",
      "city": "Henderson",
      "zipcode": "89074",
      "state": "NV",
      "country": "US"
    }
  }'

3. Connect a Company Bank Account

The easiest way to connect a company bank account is using our pre-built onboarding system. Call the EncompassFi API to get a bank setup onboard link. This bank account will be used to withdrawal any money to pay direct deposits and taxes on behalf of the company.

curl -X POST \ 
  https://sandbox.encompassfi.com/companies/<companyId>/onboard/connect_bank_account \
  -H 'Content-Type: application/json' \
  -H 'X-API-key: <API_KEY>' \
  -d '{
    "signerName": "John Smith",
    "signerTitle": "CEO",
    "signerEmail": "[email protected]"
  }'

4. Create an Employee

Employees are persons that will be paid on a W2. Unlike contractors (1099) employees can only be a person. If the company needs to pay another business, they can create a contractor instead. Employees must be assigned to one or multiple workplaces. Their assigned workplaces will determine their tax setup and how EncompassFi calculates their tax and tax requirements.

curl -X POST \ 
  https://sandbox.encompassfi.com/companies/<companyId>/employees \
  -H 'Content-Type: application/json' \
  -H 'X-API-key: <API_KEY>' \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "ssn": "333224444",
    "active": true,
    "primaryWorkplaceId": "<workplaceId>",
    "workplaces": [
      "<workplaceId>"
    ],
    "dateOfBirth": "2000-01-01",
    "startDate": "2019-08-24",
    "defaultPaymentMethod": "Manual",
    "residence": {
      "street1": "string",
      "street2": "string",
      "city": "string",
      "zipcode": "string",
      "state": "AL",
      "country": "US"
    }
  }'

5. Create a Draft Payroll

A payroll can be generated when a company needs to pay its workers. The company will need to specify who is being paid, for how much, and when. To payout a payroll, the company will need to preview the payroll to review earnings and tax payments then approve that payroll.

curl -X POST \ 
  https://sandbox.encompassfi.com/companies/<companyId>/payrolls \
  -H 'Content-Type: application/json' \
  -H 'X-API-key: <API_KEY>' \
  -d '{
    "periodStart": "2019-08-1",
    "periodEnd": "2019-08-15",
    "payday": "2019-08-15",
    "type": "Regular",
    "frequency": "Semimonthly",
    "processingPeriod": "FourDay",
    "employeeItems": [
      {
        "employeeId": "<employeeId>",
        "paymentMethod": "Manual",
        "flsaOvertimeExemption": "NonExempt",
        "supplementalTaxMethod": "Flat",
        "payments": [
          {
            "workplaceId": "<workplaceId>",
            "isSalaryRate": false,
            "payRate": 15,
            "regularHours": 86.33,
          }
        ]
      }
    ]
  }'

curl -X GET \ 
  https://sandbox.encompassfi.com/companies/<companyId>/payrolls/<payrollId>/preview \
  -H 'X-API-key: <API_KEY>'

curl -X POST \ 
  https://sandbox.encompassfi.com/companies/<companyId>/payrolls/<payrollId>/approve \
  -H 'Content-Type: application/json' \
  -H 'X-API-key: <API_KEY>'