# Gusto

> Payroll, HR and benefits for small businesses. Read your company, employees, contractors, departments, pay schedules, payrolls, contractor payments and time off, and add or update employees and contractors.

App · 21 actions. Web page: https://docs.lodol.com/docs/integrations/gusto

## Actions

### Add people to a department

Move employees and contractors into a department.

**Inputs**

- Department (`department_id`, text, required): The department to add them to.
- Employee IDs (`employee_ids`, list): Optional. The UUIDs of the employees to add.
- Contractor IDs (`contractor_ids`, list): Optional. The UUIDs of the contractors to add.
- Version (`version`, text): Optional. The record's current version, to make sure nobody changed it since you read it. Leave blank to use the latest.

**Outputs**: A department.

- `company_uuid` (text): The company's UUID.
- `contractors` (list): The contractors in it.
- `employees` (list): The employees in it.
- `title` (text): Department title.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "contractors": [
    {
      "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
    }
  ],
  "employees": [
    {
      "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c"
    }
  ],
  "title": "Engineering",
  "uuid": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
  "version": "a7d9a5ab55e6b1a8f0b6e3c3d2f1e0a9"
}
```

### Create a contractor

Add a contractor: a person (first and last name) or a business (business name), paid a fixed amount or by the hour.

**Inputs**

- Contractor type (`contractor_type`, text): An individual person, or a business. One of: `Individual`, `Business`. Default: `Individual`.
- Wage type (`wage_type`, text, required): Paid a fixed amount, or by the hour. One of: `Fixed`, `Hourly`.
- Start date (`start_date`, date, required): Their first day.
- Hourly rate (`hourly_rate`, text): The hourly rate in dollars, e.g. 45.00. Required when paid by the hour.
- First name (`first_name`, text): The legal first name (Individual contractors).
- Last name (`last_name`, text): The legal last name (Individual contractors).
- Middle initial (`middle_initial`, text): Optional.
- Business name (`business_name`, text): The business's name (Business contractors).
- EIN (`ein`, text): Optional. The business's federal EIN.
- Email (`email`, text): Their email. Required when they self-onboard.
- Work email (`work_email`, text): Optional. Their work email address.
- Contractor self-onboards (`self_onboarding`, true/false): On: Gusto invites them to enter their own details. Default: `false`.
- File a new-hire report (`file_new_hire_report`, true/false): On: Gusto files a state new-hire report (needs the work state for an Individual). Default: `false`.
- Work state (`work_state`, text): Optional. Two-letter US state code where they work, e.g. CA.

**Outputs**: A Gusto contractor.

- `address` (object): The contractor's address.
- `business_name` (text): Business name (Business).
- `company_uuid` (text): The company's UUID.
- `department` (text): Department title.
- `department_uuid` (text): Department UUID.
- `dismissal_date` (text): Dismissal date, if dismissed.
- `ein` (text): EIN (Business).
- `email` (text): Email.
- `file_new_hire_report` (true/false): Whether a new-hire report is filed.
- `first_name` (text): First name (Individual).
- `has_ein` (true/false): Whether an EIN is on file.
- `hourly_rate` (text): Hourly rate, as text.
- `is_active` (true/false): Whether the contractor is active.
- `last_name` (text): Last name (Individual).
- `middle_initial` (text): Middle initial.
- `onboarded` (true/false): Whether onboarding is complete.
- `onboarding_status` (text): Where onboarding stands.
- `payment_method` (text): Direct Deposit or Check.
- `start_date` (text): Start date.
- `type` (text): Individual or Business.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.
- `wage_type` (text): Fixed or Hourly.
- `work_email` (text): Work email.
- `work_state` (text): Work state.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "first_name": "Grace",
  "hourly_rate": "45.00",
  "is_active": true,
  "last_name": "Hopper",
  "start_date": "2026-01-05",
  "type": "Individual",
  "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "version": "b48c46abfed1487b873b442334b3c4ff",
  "wage_type": "Hourly"
}
```

### Create a department

Add a department to the company.

**Inputs**

- Title (`title`, text, required): The department's name.

**Outputs**: A department.

- `company_uuid` (text): The company's UUID.
- `contractors` (list): The contractors in it.
- `employees` (list): The employees in it.
- `title` (text): Department title.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "contractors": [],
  "employees": [],
  "title": "Engineering",
  "uuid": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
  "version": "a7d9a5ab55e6b1a8f0b6e3c3d2f1e0a9"
}
```

### Create a job

Give an employee a job with a title and hire date. Gusto needs a job, and so a hire date, before it can pay or terminate an employee. A new job starts at $0 an hour until its pay is set in Gusto.

**Inputs**

- Employee ID (`employee_id`, text, required): The employee's UUID, from 'List employees' or 'Create an employee'.
- Job title (`title`, text, required): The job title, e.g. Office Manager.
- Hire date (`hire_date`, date, required): When the employee was hired or rehired for the job.
- 2% shareholder (`two_percent_shareholder`, text): Optional. Whether they own at least 2% of the company (S corporations only). One of: `yes`, `no`.

**Outputs**: An employee's job.

- `compensations` (list): The job's compensations.
- `current_compensation_uuid` (text): The current compensation's UUID.
- `employee_uuid` (text): The employee's UUID.
- `hire_date` (text): When the employee was hired or rehired for the job.
- `location` (object): The work location.
- `location_uuid` (text): The work location's UUID.
- `payment_unit` (text): What the rate is per (with compensations:read).
- `primary` (true/false): Whether this is the employee's primary job.
- `rate` (text): Pay rate (with the compensations:read scope; $0 on a new job).
- `state_wc_class_code` (text): Washington workers' compensation risk class code.
- `state_wc_covered` (true/false): Washington workers' compensation coverage.
- `title` (text): The job title.
- `two_percent_shareholder` (true/false): Whether they own at least 2% of the company.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.

**Example output**

```json
{
  "employee_uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c",
  "hire_date": "2026-10-01",
  "payment_unit": "Hour",
  "primary": true,
  "rate": "0.00",
  "title": "Office Manager",
  "uuid": "e7f8a9b0-c1d2-4e3f-8a4b-5c6d7e8f9a0b",
  "version": "d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5"
}
```

### Create an employee

Add an employee to the company. Either they finish onboarding themselves (Gusto emails them an invitation), or an admin completes it in Gusto.

**Inputs**

- First name (`first_name`, text, required): The legal first name.
- Last name (`last_name`, text, required): The legal last name.
- Middle initial (`middle_initial`, text): Optional.
- Preferred first name (`preferred_first_name`, text): Optional. The name they go by.
- Personal email (`email`, text): Their personal email. Required when they self-onboard.
- Work email (`work_email`, text): Optional. Their work email address.
- Date of birth (`date_of_birth`, date): Optional.
- Employee self-onboards (`self_onboarding`, true/false): On: Gusto invites them to enter their own details. Off: an admin completes onboarding in Gusto. Default: `false`.

**Outputs**: A Gusto employee.

- `company_uuid` (text): The company's UUID.
- `current_employment_status` (text): full_time, part_time_..., variable or seasonal.
- `current_home_address` (object): Current home address (when included).
- `custom_fields` (list): Custom field values.
- `date_of_birth` (text): Date of birth (YYYY-MM-DD).
- `department` (text): Department title.
- `department_uuid` (text): Department UUID.
- `email` (text): Personal email.
- `employee_code` (text): The employee code.
- `first_name` (text): First name.
- `flsa_status` (text): FLSA classification.
- `has_ssn` (true/false): Whether an SSN is on file.
- `hidden_ssn` (text): The SSN, masked.
- `hired_at` (text): Hire date.
- `jobs` (list): The employee's jobs.
- `last_name` (text): Last name.
- `manager_uuid` (text): The manager's UUID.
- `middle_initial` (text): Middle initial.
- `onboarded` (true/false): Whether onboarding is complete.
- `onboarding_status` (text): Where onboarding stands.
- `payment_method` (text): Direct Deposit or Check.
- `phone` (text): Phone number.
- `preferred_first_name` (text): Preferred first name.
- `terminated` (true/false): Whether the employee is terminated.
- `terminations` (list): The employee's terminations.
- `title` (text): Job title.
- `two_percent_shareholder` (true/false): Whether they own 2% or more of an S-Corp.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.
- `warnings` (list): Gusto's warnings about the record.
- `work_email` (text): Work email.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "email": "ada@example.com",
  "first_name": "Ada",
  "jobs": [],
  "last_name": "Lovelace",
  "onboarded": true,
  "onboarding_status": "onboarding_completed",
  "terminated": false,
  "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c",
  "version": "db0edd04aaac4506f7edab03ac855d56"
}
```

### Get a contractor

Get one contractor's details, pay and status.

**Inputs**

- Contractor ID (`contractor_id`, text, required): The contractor's UUID, from 'List contractors' or 'Create a contractor'.
- Also include (`include`, list): Optional. Extra details to return with each contractor. One or more of: `company_name` (Company name), `portal_invitations` (Portal invitations).

**Outputs**: A Gusto contractor.

- `address` (object): The contractor's address.
- `business_name` (text): Business name (Business).
- `company_uuid` (text): The company's UUID.
- `department` (text): Department title.
- `department_uuid` (text): Department UUID.
- `dismissal_date` (text): Dismissal date, if dismissed.
- `ein` (text): EIN (Business).
- `email` (text): Email.
- `file_new_hire_report` (true/false): Whether a new-hire report is filed.
- `first_name` (text): First name (Individual).
- `has_ein` (true/false): Whether an EIN is on file.
- `hourly_rate` (text): Hourly rate, as text.
- `is_active` (true/false): Whether the contractor is active.
- `last_name` (text): Last name (Individual).
- `middle_initial` (text): Middle initial.
- `onboarded` (true/false): Whether onboarding is complete.
- `onboarding_status` (text): Where onboarding stands.
- `payment_method` (text): Direct Deposit or Check.
- `start_date` (text): Start date.
- `type` (text): Individual or Business.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.
- `wage_type` (text): Fixed or Hourly.
- `work_email` (text): Work email.
- `work_state` (text): Work state.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "first_name": "Grace",
  "hourly_rate": "45.00",
  "is_active": true,
  "last_name": "Hopper",
  "start_date": "2026-01-05",
  "type": "Individual",
  "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "version": "b48c46abfed1487b873b442334b3c4ff",
  "wage_type": "Hourly"
}
```

### Get a payroll

Get one payroll with each employee's pay. Money amounts are returned as text.

**Inputs**

- Payroll ID (`payroll_id`, text, required): The payroll's UUID (payroll_uuid), from 'List payrolls'.
- Also include (`include`, list): Optional. Extra details to return. One or more of: `benefits`, `deductions`, `taxes`, `payroll_status_meta` (Payroll status meta), `totals`, `risk_blockers` (Risk blockers), `reversals`, `payroll_taxes` (Payroll taxes).

**Outputs**: A payroll.

- `calculated_at` (text): When it was last calculated.
- `check_date` (text): The pay date.
- `company_uuid` (text): The company's UUID.
- `created_at` (text): When it was created.
- `employee_compensations` (list): Each employee's pay on this payroll.
- `external` (true/false): Whether it was run outside Gusto.
- `final_termination_payroll` (true/false): Whether it pays out a terminated employee.
- `off_cycle` (true/false): Whether it is an off-cycle payroll.
- `off_cycle_reason` (text): Why it is off-cycle.
- `pay_period` (object): The pay period.
- `payroll_deadline` (text): When the payroll must be submitted by.
- `payroll_status_meta` (object): Status details (when included).
- `payroll_uuid` (text): The payroll's UUID.
- `processed` (true/false): Whether the payroll has been processed.
- `processed_date` (text): When it was processed.
- `totals` (object): Money totals, as text (when 'totals' is included).
- `uuid` (text): The payroll's UUID (same as payroll_uuid).

**Example output**

```json
{
  "check_date": "2026-09-30",
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "employee_compensations": [],
  "off_cycle": false,
  "pay_period": {
    "end_date": "2026-09-30",
    "pay_schedule_uuid": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
    "start_date": "2026-09-16"
  },
  "payroll_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
  "processed": true,
  "uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
}
```

### Get an employee

Get one employee's details, jobs and status.

**Inputs**

- Employee ID (`employee_id`, text, required): The employee's UUID, from 'List employees' or 'Create an employee'.
- Also include (`include`, list): Optional. Extra details to return with each employee. One or more of: `all_compensations` (All compensations), `all_home_addresses` (All home addresses), `company_name` (Company name), `current_home_address` (Current home address), `custom_fields` (Custom fields), `portal_invitations` (Portal invitations).

**Outputs**: A Gusto employee.

- `company_uuid` (text): The company's UUID.
- `current_employment_status` (text): full_time, part_time_..., variable or seasonal.
- `current_home_address` (object): Current home address (when included).
- `custom_fields` (list): Custom field values.
- `date_of_birth` (text): Date of birth (YYYY-MM-DD).
- `department` (text): Department title.
- `department_uuid` (text): Department UUID.
- `email` (text): Personal email.
- `employee_code` (text): The employee code.
- `first_name` (text): First name.
- `flsa_status` (text): FLSA classification.
- `has_ssn` (true/false): Whether an SSN is on file.
- `hidden_ssn` (text): The SSN, masked.
- `hired_at` (text): Hire date.
- `jobs` (list): The employee's jobs.
- `last_name` (text): Last name.
- `manager_uuid` (text): The manager's UUID.
- `middle_initial` (text): Middle initial.
- `onboarded` (true/false): Whether onboarding is complete.
- `onboarding_status` (text): Where onboarding stands.
- `payment_method` (text): Direct Deposit or Check.
- `phone` (text): Phone number.
- `preferred_first_name` (text): Preferred first name.
- `terminated` (true/false): Whether the employee is terminated.
- `terminations` (list): The employee's terminations.
- `title` (text): Job title.
- `two_percent_shareholder` (true/false): Whether they own 2% or more of an S-Corp.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.
- `warnings` (list): Gusto's warnings about the record.
- `work_email` (text): Work email.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "email": "ada@example.com",
  "first_name": "Ada",
  "jobs": [],
  "last_name": "Lovelace",
  "onboarded": true,
  "onboarding_status": "onboarding_completed",
  "terminated": false,
  "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c",
  "version": "db0edd04aaac4506f7edab03ac855d56"
}
```

### Get the company

Get the connected company's name, EIN, entity type, plan, status and locations. Useful as a connection check.

**Inputs**: None.

**Outputs**: The connected Gusto company.

- `company_status` (text): Approved, Not Approved or Suspended.
- `contractor_only` (true/false): Whether the company pays only contractors.
- `ein` (text): The company's federal EIN.
- `entity_type` (text): The legal entity type, e.g. LLC or S-Corporation.
- `funding_type` (text): How payroll is funded.
- `is_suspended` (true/false): Whether the company is suspended.
- `join_date` (text): When the company joined Gusto.
- `locations` (list): The company's addresses.
- `name` (text): The company's legal name.
- `pay_schedule_type` (text): How pay schedules are assigned.
- `primary_payroll_admin` (object): The company's primary payroll admin.
- `primary_signatory` (object): The company's primary signatory.
- `slug` (text): The company's slug.
- `tier` (text): The Gusto plan, e.g. simple, plus, premium.
- `trade_name` (text): The name the company trades under.
- `uuid` (text): The record's Gusto UUID.

**Example output**

```json
{
  "company_status": "Approved",
  "entity_type": "LLC",
  "locations": [
    {
      "active": true,
      "city": "San Francisco",
      "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
      "country": "USA",
      "state": "CA",
      "street_1": "425 2nd Street",
      "uuid": "6e5d4c3b-2a19-4f8e-9d7c-6b5a4e3d2c1b",
      "version": "1928d0c378e519e9c03fb959bc959a6b",
      "zip": "94107"
    }
  ],
  "name": "Lodol Demo Co",
  "tier": "plus",
  "uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d"
}
```

### List admins

List the company's Gusto admins.

**Inputs**

- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: The admins.

- `count` (number): How many admins were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The admins.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many admins Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "email": "owner@example.com",
      "first_name": "Owner",
      "last_name": "Admin",
      "uuid": "e5f6a7b8-c9d0-4e1f-8a2b-3c4d5e6f7a8b"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List contractor payments

List what contractors were paid between two dates, per contractor or per pay date.

**Inputs**

- From (`start_date`, date, required): The first day to cover.
- To (`end_date`, date): Optional. The last day; today if blank.
- Contractor ID (`contractor_id`, text): Optional. Only this contractor's payments.
- Group by pay date (`group_by_date`, true/false): On: one entry per contractor and pay date. Off: one per contractor, with totals. Default: `false`.
- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: Contractor payments in a period.

- `contractor_payments` (list): One entry per contractor (or per contractor and date when grouped).
- `count` (number): How many entries were returned.
- `end_date` (text): The last day covered.
- `start_date` (text): The first day covered.
- `total` (object): Totals across the period (not reported when grouped by date).

**Example output**

```json
{
  "contractor_payments": [
    {
      "contractor_uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "payments": [],
      "reimbursement_total": "0.00",
      "wage_total": "900.00"
    }
  ],
  "count": 1,
  "end_date": "2026-09-30",
  "start_date": "2026-09-01",
  "total": {
    "reimbursements": "0.00",
    "wages": "900.00"
  }
}
```

### List contractors

List the company's contractors, optionally matching a name, onboarded or dismissed.

**Inputs**

- Search (`search_term`, text): Optional. Only contractors whose name contains this.
- Sort by (`sort_by`, text): Optional. One of: `created_at` (Created at), `type`, `onboarding_status` (Onboarding status), `name`.
- Sort direction (`sort_direction`, text): Optional. Ascending unless you pick descending. One of: `asc` (Ascending), `desc` (Descending).
- Also include (`include`, list): Optional. Extra details to return with each contractor. One or more of: `company_name` (Company name), `portal_invitations` (Portal invitations).
- Onboarded (`onboarded`, text): Optional. Yes for only onboarded contractors, No for only those still onboarding. One of: `yes`, `no`.
- Dismissed (`terminated`, text): Optional. Yes for only dismissed contractors, No for only current ones. One of: `yes`, `no`.
- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: The contractors.

- `count` (number): How many contractors were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The contractors.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many contractors Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
      "first_name": "Grace",
      "hourly_rate": "45.00",
      "is_active": true,
      "last_name": "Hopper",
      "start_date": "2026-01-05",
      "type": "Individual",
      "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "version": "b48c46abfed1487b873b442334b3c4ff",
      "wage_type": "Hourly"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List departments

List the company's departments and the people in each.

**Inputs**: None.

**Outputs**: The departments.

- `count` (number): How many departments were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The departments.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many departments Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
      "contractors": [
        {
          "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d"
        }
      ],
      "employees": [
        {
          "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c"
        }
      ],
      "title": "Engineering",
      "uuid": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f",
      "version": "a7d9a5ab55e6b1a8f0b6e3c3d2f1e0a9"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List employees

List the company's employees, optionally only those at one location, matching a name, onboarded or terminated.

**Inputs**

- Location (`location_id`, text): Optional. Only employees who work at this location.
- Search (`search_term`, text): Optional. Only employees whose name contains this.
- Sort by (`sort_by`, text): Optional. Cannot be combined with Search. One of: `created_at` (Created at), `name`, `onboarding_status` (Onboarding status).
- Sort direction (`sort_direction`, text): Optional. Ascending unless you pick descending. One of: `asc` (Ascending), `desc` (Descending).
- Also include (`include`, list): Optional. Extra details to return with each employee. One or more of: `all_compensations` (All compensations), `all_home_addresses` (All home addresses), `company_name` (Company name), `current_home_address` (Current home address), `custom_fields` (Custom fields), `portal_invitations` (Portal invitations).
- Onboarded (`onboarded`, text): Optional. Yes for only onboarded employees, No for only those still onboarding. One of: `yes`, `no`.
- Terminated (`terminated`, text): Optional. Yes for only terminated employees, No for only current ones. One of: `yes`, `no`.
- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: The employees.

- `count` (number): How many employees were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The employees.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many employees Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
      "email": "ada@example.com",
      "first_name": "Ada",
      "jobs": [],
      "last_name": "Lovelace",
      "onboarded": true,
      "onboarding_status": "onboarding_completed",
      "terminated": false,
      "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c",
      "version": "db0edd04aaac4506f7edab03ac855d56"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List locations

List the company's addresses and work locations.

**Inputs**

- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: The locations.

- `count` (number): How many locations were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The locations.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many locations Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "active": true,
      "city": "San Francisco",
      "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
      "country": "USA",
      "state": "CA",
      "street_1": "425 2nd Street",
      "uuid": "6e5d4c3b-2a19-4f8e-9d7c-6b5a4e3d2c1b",
      "version": "1928d0c378e519e9c03fb959bc959a6b",
      "zip": "94107"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List pay schedules

List the company's pay schedules and how often they pay.

**Inputs**

- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: The pay schedules.

- `count` (number): How many pay schedules were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The pay schedules.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many pay schedules Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "active": true,
      "anchor_pay_date": "2026-01-15",
      "custom_name": "Twice monthly",
      "day_1": 15,
      "day_2": 31,
      "frequency": "Twice per month",
      "uuid": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
      "version": "68934a3e9455fa72420237eb05902327"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List payrolls

List payrolls. With nothing chosen Gusto returns the processed regular payrolls of the past six months. The end date can be at most three months ahead, and the dates at most a year apart.

**Inputs**

- Processing status (`processing_statuses`, list): Optional. Processed, unprocessed, or both. Gusto's default is processed. One or more of: `processed`, `unprocessed`.
- Payroll types (`payroll_types`, list): Optional. Gusto's default is regular payrolls only. One or more of: `regular`, `off_cycle` (Off-cycle), `external`.
- Also include (`include`, list): Optional. Extra details to return with each payroll. One or more of: `taxes`, `payroll_status_meta` (Payroll status meta), `totals`, `risk_blockers` (Risk blockers), `reversals`.
- From (`start_date`, date): Optional. Payrolls on or after this date.
- To (`end_date`, date): Optional. Payrolls on or before this date.
- Order (`sort_order`, text): Optional. Oldest or newest first. One of: `asc` (Oldest first), `desc` (Newest first).
- Page (`page`, number): Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records). At least 1.
- Per page (`per_page`, number): Optional. How many records per page, 1 to 100. From 1 to 100.

**Outputs**: The payrolls.

- `count` (number): How many payrolls were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The payrolls.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many payrolls Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "check_date": "2026-09-30",
      "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
      "off_cycle": false,
      "pay_period": {
        "end_date": "2026-09-30",
        "pay_schedule_uuid": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
        "start_date": "2026-09-16"
      },
      "payroll_uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "processed": true,
      "uuid": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### List time-off requests

List employees' time-off requests, optionally in a date range.

**Inputs**

- From (`start_date`, date): Optional. Requests starting on or after this date.
- To (`end_date`, date): Optional. Requests ending on or before this date.

**Outputs**: The time-off requests.

- `count` (number): How many time-off requests were returned.
- `has_more` (true/false): Whether more records exist than were returned.
- `items` (list): The time-off requests.
- `page` (number): The page fetched, or empty when every page was fetched.
- `total_count` (number): How many time-off requests Gusto has in all.

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "days": {
        "2026-11-02": "8.000"
      },
      "employee": {
        "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c"
      },
      "policy_type": "vacation",
      "status": "approved",
      "uuid": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f"
    }
  ],
  "page": null,
  "total_count": 1
}
```

### Terminate an employee

Record an employee's last day of work.

**Inputs**

- Employee ID (`employee_id`, text, required): The employee's UUID, from 'List employees' or 'Create an employee'.
- Last day of work (`effective_date`, date, required): The employee's last day of work.
- Pay final wages off-cycle (`run_termination_payroll`, true/false): On: pay their final wages in an off-cycle payroll. Off: pay them on the next regular payroll. Default: `false`.

**Outputs**: An employee's termination.

- `active` (true/false): Whether the termination is in effect.
- `cancelable` (true/false): Whether it can still be cancelled.
- `effective_date` (text): The last day of work.
- `employee_uuid` (text): The employee's UUID.
- `run_termination_payroll` (true/false): Whether final wages go out in an off-cycle payroll.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.

**Example output**

```json
{
  "active": true,
  "cancelable": true,
  "effective_date": "2026-10-31",
  "employee_uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c",
  "run_termination_payroll": false,
  "uuid": "f6a7b8c9-d0e1-4f2a-9b3c-4d5e6f7a8b9c",
  "version": "d487dd0b55dfcacdd920ccbdaeafa351"
}
```

### Update a contractor

Change a contractor's details, pay or active flag. Fields left blank are not changed.

**Inputs**

- Contractor ID (`contractor_id`, text, required): The contractor's UUID, from 'List contractors' or 'Create a contractor'.
- Contractor type (`contractor_type`, text): Optional. An individual person, or a business. One of: `Individual`, `Business`.
- Wage type (`wage_type`, text): Optional. Paid a fixed amount, or by the hour. One of: `Fixed`, `Hourly`.
- Start date (`start_date`, date): Optional. Their first day.
- Hourly rate (`hourly_rate`, text): The hourly rate in dollars, e.g. 45.00. Required when paid by the hour.
- First name (`first_name`, text): The legal first name.
- Last name (`last_name`, text): The legal last name.
- Middle initial (`middle_initial`, text): Optional.
- Business name (`business_name`, text): The business's name (Business contractors).
- EIN (`ein`, text): Optional. The business's federal EIN.
- Email (`email`, text): Optional. Their email.
- Work email (`work_email`, text): Optional. Their work email address.
- File a new-hire report (`file_new_hire_report`, text): Optional. Whether Gusto files a state new-hire report. One of: `yes`, `no`.
- Work state (`work_state`, text): Optional. Two-letter US state code where they work, e.g. CA.
- Active (`is_active`, text): Optional. No deactivates the contractor; Yes reactivates them. One of: `yes`, `no`.
- Version (`version`, text): Optional. The record's current version, to make sure nobody changed it since you read it. Leave blank to use the latest.

**Outputs**: A Gusto contractor.

- `address` (object): The contractor's address.
- `business_name` (text): Business name (Business).
- `company_uuid` (text): The company's UUID.
- `department` (text): Department title.
- `department_uuid` (text): Department UUID.
- `dismissal_date` (text): Dismissal date, if dismissed.
- `ein` (text): EIN (Business).
- `email` (text): Email.
- `file_new_hire_report` (true/false): Whether a new-hire report is filed.
- `first_name` (text): First name (Individual).
- `has_ein` (true/false): Whether an EIN is on file.
- `hourly_rate` (text): Hourly rate, as text.
- `is_active` (true/false): Whether the contractor is active.
- `last_name` (text): Last name (Individual).
- `middle_initial` (text): Middle initial.
- `onboarded` (true/false): Whether onboarding is complete.
- `onboarding_status` (text): Where onboarding stands.
- `payment_method` (text): Direct Deposit or Check.
- `start_date` (text): Start date.
- `type` (text): Individual or Business.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.
- `wage_type` (text): Fixed or Hourly.
- `work_email` (text): Work email.
- `work_state` (text): Work state.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "first_name": "Grace",
  "hourly_rate": "45.00",
  "is_active": true,
  "last_name": "Hopper",
  "start_date": "2026-01-05",
  "type": "Individual",
  "uuid": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "version": "b48c46abfed1487b873b442334b3c4ff",
  "wage_type": "Hourly"
}
```

### Update an employee

Change an employee's name, emails, date of birth or 2% shareholder flag. Fields left blank are not changed.

**Inputs**

- Employee ID (`employee_id`, text, required): The employee's UUID, from 'List employees' or 'Create an employee'.
- First name (`first_name`, text): The legal first name.
- Last name (`last_name`, text): The legal last name.
- Middle initial (`middle_initial`, text): Optional.
- Preferred first name (`preferred_first_name`, text): Optional. The name they go by.
- Personal email (`email`, text): Optional. Their personal email.
- Work email (`work_email`, text): Optional. Their work email address.
- Date of birth (`date_of_birth`, date): Optional.
- 2% shareholder (`two_percent_shareholder`, text): Optional. Whether they own 2% or more of the company (S corporations only). One of: `yes`, `no`.
- Version (`version`, text): Optional. The record's current version, to make sure nobody changed it since you read it. Leave blank to use the latest.

**Outputs**: A Gusto employee.

- `company_uuid` (text): The company's UUID.
- `current_employment_status` (text): full_time, part_time_..., variable or seasonal.
- `current_home_address` (object): Current home address (when included).
- `custom_fields` (list): Custom field values.
- `date_of_birth` (text): Date of birth (YYYY-MM-DD).
- `department` (text): Department title.
- `department_uuid` (text): Department UUID.
- `email` (text): Personal email.
- `employee_code` (text): The employee code.
- `first_name` (text): First name.
- `flsa_status` (text): FLSA classification.
- `has_ssn` (true/false): Whether an SSN is on file.
- `hidden_ssn` (text): The SSN, masked.
- `hired_at` (text): Hire date.
- `jobs` (list): The employee's jobs.
- `last_name` (text): Last name.
- `manager_uuid` (text): The manager's UUID.
- `middle_initial` (text): Middle initial.
- `onboarded` (true/false): Whether onboarding is complete.
- `onboarding_status` (text): Where onboarding stands.
- `payment_method` (text): Direct Deposit or Check.
- `phone` (text): Phone number.
- `preferred_first_name` (text): Preferred first name.
- `terminated` (true/false): Whether the employee is terminated.
- `terminations` (list): The employee's terminations.
- `title` (text): Job title.
- `two_percent_shareholder` (true/false): Whether they own 2% or more of an S-Corp.
- `uuid` (text): The record's Gusto UUID.
- `version` (text): The record's current version, needed to update it.
- `warnings` (list): Gusto's warnings about the record.
- `work_email` (text): Work email.

**Example output**

```json
{
  "company_uuid": "c9f4d3c2-1b8a-4e6f-9d2c-3a1b5e7f9c0d",
  "email": "ada@example.com",
  "first_name": "Ada",
  "jobs": [],
  "last_name": "Lovelace",
  "onboarded": true,
  "onboarding_status": "onboarding_completed",
  "terminated": false,
  "uuid": "7757500e-b7a5-4f0a-a2ad-1f8e5d8b7e2c",
  "version": "db0edd04aaac4506f7edab03ac855d56"
}
```