The Employee Object

The employee object is the core record for anyone who works at a company in Friday — whether they are a full-payroll employee, a contractor, or an administrator. Each object represents a single employment relationship between a person and a company under a specific role.

For conceptual details on employment types, one-person-multiple-records, and timetrack-only employees, see the Employee guide.

Variants

Shape	Returned by	Extra fields
List item	`GET /employees`	`current_earning`
Detail	`GET /employees/:employee_id`	Everything in the list item, plus `recovery_email`, `work_phone_ext`, `daily_time_limit`, `weekly_time_limit`, `paid_lunch_time`, `lunch_in_overtime`, `created_at`, and `earning_history`

The detail shape is a superset of the list shape.

Field Reference

Core identity fields

Field	Type	Description
`employee_id`	integer	Unique identifier for this employee record.
`first_name`	string	First name.
`last_name`	string	Last name.
`middle_name`	string \| null	Middle name or initial.
`email`	string	Primary email address.
`nickname`	string \| null	Preferred name / display name.
`dob`	string \| null	Date of birth in `YYYY-MM-DD` format.

Employment status fields

Field	Type	Description
`is_active`	boolean	Whether the employee is currently active. Inactive employees have been offboarded or dismissed.
`status`	string \| null	Freeform employment status (e.g. `"active"`, `"dismissed"`).
`onboarding_status`	string	Where the employee is in the onboarding flow. Values: `"completed"`, `"needs_attention"`, `"blocking"`.
`start_date`	date-time \| null	The employee's start date at the company.

Classification fields

Field	Type	Description
`employment_type`	string \| null	The classification of this employee record. Values: `"admin"`, `"employee"`, `"contractor"`.
`timetrack_only`	boolean \| null	Whether this employee is excluded from payroll (time tracking only).
`contractor_type`	string \| null	For contractors, indicates the sub-type (e.g. `"individual"`, `"business"`). Null for non-contractors.

Contact fields

Field	Type	Description
`mobile_phone`	string \| null	Mobile phone number.
`home_phone`	string \| null	Home phone number.
`recovery_email`	string \| null	(Detail only) Alternate email for account recovery.
`work_phone_ext`	string \| null	(Detail only) Work phone with extension.

Time tracking fields

Field	Type	Description
`daily_time_limit`	number \| null	(Detail only) Maximum hours per day. Used for alerts, not hard enforcement.
`weekly_time_limit`	number \| null	(Detail only) Maximum hours per week.
`paid_lunch_time`	integer \| null	(Detail only) Paid lunch time in minutes.
`lunch_in_overtime`	boolean \| null	(Detail only) Whether paid lunch minutes count toward overtime calculations.

Organizational fields

Field	Type	Description
`department`	Department \| null	The department the employee belongs to, with `department_id` and `name`. Null if unassigned.
`pay_schedule_group`	object \| null	The pay schedule group the employee is assigned to, with `pay_schedule_group_id` and `name`. See Pay Schedule Group.
`address`	Address \| null	The employee's home address.

Earnings fields

Field	Type	Description
`current_earning`	Earning \| null	The most recent earning record with an effective date on or before today. Null if no earning record exists.
`earning_history`	array	(Detail only) All earning records ordered by `start_date` descending. See Earning.

Metadata

Field	Type	Description
`created_at`	date-time	(Detail only) When this employee record was created.

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

{
  "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
    }
  ]
}

The Earning Object

An earning record represents an employee's compensation configuration at a point in time. Each record has an effective start_date, and the current earning is the most recent record with a start date on or before today.

Earnings appear as nested objects within the employee object: current_earning on both list and detail shapes, and earning_history (the full array) on the detail shape only.

Field Reference

Field	Type	Description
`employee_earnings_id`	integer	Unique identifier for this earning record.
`start_date`	date-time	Effective date for this earning configuration.
`payment_unit`	string \| null	How the employee is paid. See Payment Units below.
`salary_type`	string \| null	For salaried employees, the pay period the salary figure represents. See Salary Types below.
`payment_amount`	number \| null	Hourly rate for hourly payment units ($/hr).
`salary`	number \| null	Salary amount per the `salary_type` period.
`overtime_amount`	number \| null	Overtime rate multiplier (e.g. `1.5` for time-and-a-half).
`default_hours`	number \| null	Default weekly hours for this employee.
`pto_payment_amount`	number \| null	Hourly rate used when paying out PTO ($/hr).

Payment Units

Value	Description
`"hour"`	Paid by the hour. `payment_amount` is the hourly rate.
`"salary"`	Salaried. `salary` holds the amount; `salary_type` specifies the period.
`"hourly_salary"`	Salaried but tracked hourly (hybrid). Both `salary` and `payment_amount` may be set.
`"yearly"`	Annual flat rate.
`"weekly"`	Weekly flat rate.
`"biweekly"`	Biweekly flat rate.
`"monthly"`	Monthly flat rate.

Salary Types

Value	Description
`"yearly"`	Salary figure is an annual amount.
`"quarterly"`	Salary figure is a quarterly amount.
`"monthly"`	Salary figure is a monthly amount.
`"semimonthly"`	Salary figure is a semimonthly amount.
`"weekly"`	Salary figure is a weekly amount.
`"biweekly"`	Salary figure is a biweekly amount.

Example

{
  "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
}