The Employee Object

Overview

When you call GET /employees or GET /employees/:employee_id, you get back an employee object (or a list of them). Each object represents a single employment relationship between a person and a company under a specific role.

There are two shapes of the employee object:

The detail shape is a superset of the list shape — every field on the list item is present on the detail object.

Field Reference

Core identity fields

Employment status fields

Classification fields

Contact fields

Time tracking fields

Organizational fields

Earnings fields

Metadata

Employment Types

Every employee record has an employment_type that describes the person's role within the company. There are three possible values:

How employment types affect the data

• Earnings: Only employee and contractor types have earning records (current_earning / earning_history). Admins do not have compensation data.
• Contractor fields: The contractor_type field is only populated for contractor records. It describes whether the contractor is an individual or a business entity.
• Manager type: Only admin types can have a manager type assigned (see Manager Types).
• Workplace: Only employee types are required to have a payroll workplace on payroll/premium plans.

One Person, Multiple Records

A single person (identified by email) can be invited to the same company under different employment types. For example, someone might be both an admin and an employee at the same company. When this happens:

• The person has two separate employee records, each with its own employee_id.
• Each record has its own employment_type, is_active status, earnings, and other per-record fields.
• The GET /employees endpoint returns both records as separate items in the list.
• You can filter by employment_type to see only one type at a time.

This is common in small businesses where an owner or manager handles both administrative duties and regular work, or where a contractor is later hired as a full-time employee but retains their contractor record for historical purposes.

Duplicate check — The API prevents inviting the same email with the same employment type twice. You'll receive a 400 error if the person already has an active record of that type. But inviting the same email as a different type (e.g. adding an admin record for someone who already has an employee record) is perfectly valid.

Timetrack Only

The timetrack_only flag controls whether an employee is included in payroll processing.

When to use timetrack only

Timetrack-only is useful when you need to track someone's hours but don't process their pay through Friday. Common scenarios:

• Employees paid through a separate payroll system
• Seasonal or temporary workers who only need time tracking
• Volunteers whose hours need to be recorded

Rules

• timetrack_only applies to employee and contractor types only. It is always false for admin types.
• On timetracking plans, timetrack_only is not accepted in the invite request because all employees on a timetracking plan are inherently time-track-only (payroll is not available).
• On payroll/premium plans, timetrack_only defaults to false if omitted, meaning the employee will be included in payroll.
• When timetrack_only is true, payroll-specific fields like workplace, payment_unit, and wage fields are not required during invitation.

Manager Types

Admin employees can optionally be assigned a manager_type that defines the scope of their administrative permissions. Manager types are only available on premium plans.

If no manager_type is set, an admin has the default admin permissions.

Plan requirement — Manager types are a premium feature. On timetracking and payroll plans, the manager_type field is not accepted. Attempting to set it on a non-premium plan returns a 400 error.

Earnings

Earnings represent an employee's compensation configuration. Each earning record has an effective start_date, and the current earning is the most recent record with a start date on or before today.

How earnings work

• When you invite an employee with wage fields (payment_unit, payment_amount, etc.), an initial earning record is created.
• The detail endpoint returns the full earning_history array, letting you see all past and scheduled future compensation changes.
• The list endpoint returns only current_earning for efficiency.
• Admins typically don't have earning records since they are not compensated through the payroll system.

Example: List Item

{
  "employee_id": 25,
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": null,
  "email": "[email protected]",
  "nickname": null,
  "dob": "1990-05-15",
  "is_active": true,
  "onboarding_status": "completed",
  "start_date": "2023-06-01T00:00:00.000Z",
  "status": "active",
  "mobile_phone": "+1-555-987-6543",
  "home_phone": null,
  "contractor_type": null,
  "timetrack_only": false,
  "employment_type": "employee",
  "department": {
    "department_id": 5,
    "name": "Engineering"
  },
  "pay_schedule_group": {
    "pay_schedule_group_id": 3,
    "name": "Biweekly"
  },
  "address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "current_earning": {
    "employee_earnings_id": 42,
    "start_date": "2024-01-01T00:00:00.000Z",
    "payment_unit": "hour",
    "salary_type": null,
    "payment_amount": 35.00,
    "salary": null,
    "overtime_amount": 1.5,
    "default_hours": 40,
    "pto_payment_amount": 35.00
  }
}

Example: Detail Object

{
  "employee_id": 25,
  "first_name": "John",
  "last_name": "Doe",
  "middle_name": null,
  "email": "[email protected]",
  "nickname": null,
  "dob": "1990-05-15",
  "is_active": true,
  "onboarding_status": "completed",
  "start_date": "2023-06-01T00:00:00.000Z",
  "status": "active",
  "mobile_phone": "+1-555-987-6543",
  "home_phone": null,
  "contractor_type": null,
  "timetrack_only": false,
  "employment_type": "employee",
  "department": {
    "department_id": 5,
    "name": "Engineering"
  },
  "pay_schedule_group": {
    "pay_schedule_group_id": 3,
    "name": "Biweekly"
  },
  "address": {
    "address_line_1": "123 Main St",
    "address_line_2": "Apt 4B",
    "city": "New York",
    "state": "NY",
    "zip": "10001",
    "country": "US"
  },
  "recovery_email": "[email protected]",
  "work_phone_ext": null,
  "daily_time_limit": 8,
  "weekly_time_limit": 40,
  "paid_lunch_time": 30,
  "lunch_in_overtime": false,
  "created_at": "2023-06-01T14:30:00.000Z",
  "current_earning": {
    "employee_earnings_id": 42,
    "start_date": "2024-01-01T00:00:00.000Z",
    "payment_unit": "hour",
    "salary_type": null,
    "payment_amount": 35.00,
    "salary": null,
    "overtime_amount": 1.5,
    "default_hours": 40,
    "pto_payment_amount": 35.00
  },
  "earning_history": [
    {
      "employee_earnings_id": 42,
      "start_date": "2024-01-01T00:00:00.000Z",
      "payment_unit": "hour",
      "salary_type": null,
      "payment_amount": 35.00,
      "salary": null,
      "overtime_amount": 1.5,
      "default_hours": 40,
      "pto_payment_amount": 35.00
    },
    {
      "employee_earnings_id": 18,
      "start_date": "2023-06-01T00:00:00.000Z",
      "payment_unit": "hour",
      "salary_type": null,
      "payment_amount": 28.00,
      "salary": null,
      "overtime_amount": 1.5,
      "default_hours": 40,
      "pto_payment_amount": 28.00
    }
  ]
}

Filtering Employees

The GET /employees endpoint supports several query parameters for filtering:

Remember that if a person has multiple employee records (e.g. both admin and employee), filtering by employment_type=employee will return only their employee record, not their admin record.

What's Next

• Invite employees — See the Inviting an Employee guide for a walkthrough of the invite endpoint, including which fields are required for each employment type and plan.
• Update employees — Use PATCH /employees/:employee_id to update profile fields, addresses, departments, and workplaces.
• Track time — Once employees exist, you can clock them in and out via the Time Records endpoints.
• Process payroll — Employees with earnings are included in payroll runs. See the Payroll Processing guide.