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.

Actions

Action	What it does
Add people to a department	Move employees and contractors into a department.
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.
Create a department	Add a department to the company.
Create a job	Give an employee a job with a title and hire date.
Create an employee	Add an employee to the company.
Get a contractor	Get one contractor's details, pay and status.
Get a payroll	Get one payroll with each employee's pay.
Get an employee	Get one employee's details, jobs and status.
Get the company	Get the connected company's name, EIN, entity type, plan, status and locations.
List admins	List the company's Gusto admins.
List contractor payments	List what contractors were paid between two dates, per contractor or per pay date.
List contractors	List the company's contractors, optionally matching a name, onboarded or dismissed.
List departments	List the company's departments and the people in each.
List employees	List the company's employees, optionally only those at one location, matching a name, onboarded or terminated.
List locations	List the company's addresses and work locations.
List pay schedules	List the company's pay schedules and how often they pay.
List payrolls	List payrolls.
List time-off requests	List employees' time-off requests, optionally in a date range.
Terminate an employee	Record an employee's last day of work.
Update a contractor	Change a contractor's details, pay or active flag.
Update an employee	Change an employee's name, emails, date of birth or 2% shareholder flag.

Add people to a department

Move employees and contractors into a department.

Inputs

Departmentdepartment_idtextRequired: The department to add them to.
Employee IDsemployee_idslist: Optional. The UUIDs of the employees to add.
Contractor IDscontractor_idslist: Optional. The UUIDs of the contractors to add.
Versionversiontext: 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_uuidtext: The company's UUID.
contractorslist: The contractors in it.
employeeslist: The employees in it.
titletext: Department title.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.

Example output

{
  "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 typecontractor_typetext: An individual person, or a business.One of: Individual, Business. Default: Individual.
Wage typewage_typetextRequired: Paid a fixed amount, or by the hour.One of: Fixed, Hourly.
Start datestart_datedateRequired: Their first day.
Hourly ratehourly_ratetext: The hourly rate in dollars, e.g. 45.00. Required when paid by the hour.
First namefirst_nametext: The legal first name (Individual contractors).
Last namelast_nametext: The legal last name (Individual contractors).
Middle initialmiddle_initialtext: Optional.
Business namebusiness_nametext: The business's name (Business contractors).
EINeintext: Optional. The business's federal EIN.
Emailemailtext: Their email. Required when they self-onboard.
Work emailwork_emailtext: Optional. Their work email address.
Contractor self-onboardsself_onboardingtrue/false: On: Gusto invites them to enter their own details.Default: false.
File a new-hire reportfile_new_hire_reporttrue/false: On: Gusto files a state new-hire report (needs the work state for an Individual).Default: false.
Work statework_statetext: Optional. Two-letter US state code where they work, e.g. CA.

Outputs

A Gusto contractor.

addressobject: The contractor's address.
business_nametext: Business name (Business).
company_uuidtext: The company's UUID.
departmenttext: Department title.
department_uuidtext: Department UUID.
dismissal_datetext: Dismissal date, if dismissed.
eintext: EIN (Business).
emailtext: Email.
file_new_hire_reporttrue/false: Whether a new-hire report is filed.
first_nametext: First name (Individual).
has_eintrue/false: Whether an EIN is on file.
hourly_ratetext: Hourly rate, as text.
is_activetrue/false: Whether the contractor is active.
last_nametext: Last name (Individual).
middle_initialtext: Middle initial.
onboardedtrue/false: Whether onboarding is complete.
onboarding_statustext: Where onboarding stands.
payment_methodtext: Direct Deposit or Check.
start_datetext: Start date.
typetext: Individual or Business.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.
wage_typetext: Fixed or Hourly.
work_emailtext: Work email.
work_statetext: Work state.

Example output

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

TitletitletextRequired: The department's name.

Outputs

A department.

company_uuidtext: The company's UUID.
contractorslist: The contractors in it.
employeeslist: The employees in it.
titletext: Department title.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.

Example output

{
  "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 IDemployee_idtextRequired: The employee's UUID, from 'List employees' or 'Create an employee'.
Job titletitletextRequired: The job title, e.g. Office Manager.
Hire datehire_datedateRequired: When the employee was hired or rehired for the job.
2% shareholdertwo_percent_shareholdertext: Optional. Whether they own at least 2% of the company (S corporations only).One of: yes, no.

Outputs

An employee's job.

compensationslist: The job's compensations.
current_compensation_uuidtext: The current compensation's UUID.
employee_uuidtext: The employee's UUID.
hire_datetext: When the employee was hired or rehired for the job.
locationobject: The work location.
location_uuidtext: The work location's UUID.
payment_unittext: What the rate is per (with compensations:read).
primarytrue/false: Whether this is the employee's primary job.
ratetext: Pay rate (with the compensations:read scope; $0 on a new job).
state_wc_class_codetext: Washington workers' compensation risk class code.
state_wc_coveredtrue/false: Washington workers' compensation coverage.
titletext: The job title.
two_percent_shareholdertrue/false: Whether they own at least 2% of the company.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.

Example output

{
  "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 namefirst_nametextRequired: The legal first name.
Last namelast_nametextRequired: The legal last name.
Middle initialmiddle_initialtext: Optional.
Preferred first namepreferred_first_nametext: Optional. The name they go by.
Personal emailemailtext: Their personal email. Required when they self-onboard.
Work emailwork_emailtext: Optional. Their work email address.
Date of birthdate_of_birthdate: Optional.
Employee self-onboardsself_onboardingtrue/false: On: Gusto invites them to enter their own details. Off: an admin completes onboarding in Gusto.Default: false.

Outputs

A Gusto employee.

company_uuidtext: The company's UUID.
current_employment_statustext: full_time, part_time_..., variable or seasonal.
current_home_addressobject: Current home address (when included).
custom_fieldslist: Custom field values.
date_of_birthtext: Date of birth (YYYY-MM-DD).
departmenttext: Department title.
department_uuidtext: Department UUID.
emailtext: Personal email.
employee_codetext: The employee code.
first_nametext: First name.
flsa_statustext: FLSA classification.
has_ssntrue/false: Whether an SSN is on file.
hidden_ssntext: The SSN, masked.
hired_attext: Hire date.
jobslist: The employee's jobs.
last_nametext: Last name.
manager_uuidtext: The manager's UUID.
middle_initialtext: Middle initial.
onboardedtrue/false: Whether onboarding is complete.
onboarding_statustext: Where onboarding stands.
payment_methodtext: Direct Deposit or Check.
phonetext: Phone number.
preferred_first_nametext: Preferred first name.
terminatedtrue/false: Whether the employee is terminated.
terminationslist: The employee's terminations.
titletext: Job title.
two_percent_shareholdertrue/false: Whether they own 2% or more of an S-Corp.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.
warningslist: Gusto's warnings about the record.
work_emailtext: Work email.

Example output

{
  "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 IDcontractor_idtextRequired: The contractor's UUID, from 'List contractors' or 'Create a contractor'.
Also includeincludelist: Optional. Extra details to return with each contractor.One or more of: company_name (Company name), portal_invitations (Portal invitations).

Outputs

A Gusto contractor.

addressobject: The contractor's address.
business_nametext: Business name (Business).
company_uuidtext: The company's UUID.
departmenttext: Department title.
department_uuidtext: Department UUID.
dismissal_datetext: Dismissal date, if dismissed.
eintext: EIN (Business).
emailtext: Email.
file_new_hire_reporttrue/false: Whether a new-hire report is filed.
first_nametext: First name (Individual).
has_eintrue/false: Whether an EIN is on file.
hourly_ratetext: Hourly rate, as text.
is_activetrue/false: Whether the contractor is active.
last_nametext: Last name (Individual).
middle_initialtext: Middle initial.
onboardedtrue/false: Whether onboarding is complete.
onboarding_statustext: Where onboarding stands.
payment_methodtext: Direct Deposit or Check.
start_datetext: Start date.
typetext: Individual or Business.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.
wage_typetext: Fixed or Hourly.
work_emailtext: Work email.
work_statetext: Work state.

Example output

{
  "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 IDpayroll_idtextRequired: The payroll's UUID (payroll_uuid), from 'List payrolls'.
Also includeincludelist: 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_attext: When it was last calculated.
check_datetext: The pay date.
company_uuidtext: The company's UUID.
created_attext: When it was created.
employee_compensationslist: Each employee's pay on this payroll.
externaltrue/false: Whether it was run outside Gusto.
final_termination_payrolltrue/false: Whether it pays out a terminated employee.
off_cycletrue/false: Whether it is an off-cycle payroll.
off_cycle_reasontext: Why it is off-cycle.
pay_periodobject: The pay period.
payroll_deadlinetext: When the payroll must be submitted by.
payroll_status_metaobject: Status details (when included).
payroll_uuidtext: The payroll's UUID.
processedtrue/false: Whether the payroll has been processed.
processed_datetext: When it was processed.
totalsobject: Money totals, as text (when 'totals' is included).
uuidtext: The payroll's UUID (same as payroll_uuid).

Example output

{
  "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 IDemployee_idtextRequired: The employee's UUID, from 'List employees' or 'Create an employee'.
Also includeincludelist: 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_uuidtext: The company's UUID.
current_employment_statustext: full_time, part_time_..., variable or seasonal.
current_home_addressobject: Current home address (when included).
custom_fieldslist: Custom field values.
date_of_birthtext: Date of birth (YYYY-MM-DD).
departmenttext: Department title.
department_uuidtext: Department UUID.
emailtext: Personal email.
employee_codetext: The employee code.
first_nametext: First name.
flsa_statustext: FLSA classification.
has_ssntrue/false: Whether an SSN is on file.
hidden_ssntext: The SSN, masked.
hired_attext: Hire date.
jobslist: The employee's jobs.
last_nametext: Last name.
manager_uuidtext: The manager's UUID.
middle_initialtext: Middle initial.
onboardedtrue/false: Whether onboarding is complete.
onboarding_statustext: Where onboarding stands.
payment_methodtext: Direct Deposit or Check.
phonetext: Phone number.
preferred_first_nametext: Preferred first name.
terminatedtrue/false: Whether the employee is terminated.
terminationslist: The employee's terminations.
titletext: Job title.
two_percent_shareholdertrue/false: Whether they own 2% or more of an S-Corp.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.
warningslist: Gusto's warnings about the record.
work_emailtext: Work email.

Example output

{
  "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_statustext: Approved, Not Approved or Suspended.
contractor_onlytrue/false: Whether the company pays only contractors.
eintext: The company's federal EIN.
entity_typetext: The legal entity type, e.g. LLC or S-Corporation.
funding_typetext: How payroll is funded.
is_suspendedtrue/false: Whether the company is suspended.
join_datetext: When the company joined Gusto.
locationslist: The company's addresses.
nametext: The company's legal name.
pay_schedule_typetext: How pay schedules are assigned.
primary_payroll_adminobject: The company's primary payroll admin.
primary_signatoryobject: The company's primary signatory.
slugtext: The company's slug.
tiertext: The Gusto plan, e.g. simple, plus, premium.
trade_nametext: The name the company trades under.
uuidtext: The record's Gusto UUID.

Example output

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

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

Outputs

The admins.

countnumber: How many admins were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The admins.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many admins Gusto has in all.

Example output

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

Fromstart_datedateRequired: The first day to cover.
Toend_datedate: Optional. The last day; today if blank.
Contractor IDcontractor_idtext: Optional. Only this contractor's payments.
Group by pay dategroup_by_datetrue/false: On: one entry per contractor and pay date. Off: one per contractor, with totals.Default: false.
Pagepagenumber: Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records).At least 1.
Per pageper_pagenumber: Optional. How many records per page, 1 to 100.From 1 to 100.

Outputs

Contractor payments in a period.

contractor_paymentslist: One entry per contractor (or per contractor and date when grouped).
countnumber: How many entries were returned.
end_datetext: The last day covered.
start_datetext: The first day covered.
totalobject: Totals across the period (not reported when grouped by date).

Example output

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

Searchsearch_termtext: Optional. Only contractors whose name contains this.
Sort bysort_bytext: Optional.One of: created_at (Created at), type, onboarding_status (Onboarding status), name.
Sort directionsort_directiontext: Optional. Ascending unless you pick descending.One of: asc (Ascending), desc (Descending).
Also includeincludelist: Optional. Extra details to return with each contractor.One or more of: company_name (Company name), portal_invitations (Portal invitations).
Onboardedonboardedtext: Optional. Yes for only onboarded contractors, No for only those still onboarding.One of: yes, no.
Dismissedterminatedtext: Optional. Yes for only dismissed contractors, No for only current ones.One of: yes, no.
Pagepagenumber: Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records).At least 1.
Per pageper_pagenumber: Optional. How many records per page, 1 to 100.From 1 to 100.

Outputs

The contractors.

countnumber: How many contractors were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The contractors.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many contractors Gusto has in all.

Example output

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

countnumber: How many departments were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The departments.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many departments Gusto has in all.

Example output

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

Locationlocation_idtext: Optional. Only employees who work at this location.
Searchsearch_termtext: Optional. Only employees whose name contains this.
Sort bysort_bytext: Optional. Cannot be combined with Search.One of: created_at (Created at), name, onboarding_status (Onboarding status).
Sort directionsort_directiontext: Optional. Ascending unless you pick descending.One of: asc (Ascending), desc (Descending).
Also includeincludelist: 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).
Onboardedonboardedtext: Optional. Yes for only onboarded employees, No for only those still onboarding.One of: yes, no.
Terminatedterminatedtext: Optional. Yes for only terminated employees, No for only current ones.One of: yes, no.
Pagepagenumber: Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records).At least 1.
Per pageper_pagenumber: Optional. How many records per page, 1 to 100.From 1 to 100.

Outputs

The employees.

countnumber: How many employees were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The employees.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many employees Gusto has in all.

Example output

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

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

Outputs

The locations.

countnumber: How many locations were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The locations.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many locations Gusto has in all.

Example output

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

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

Outputs

The pay schedules.

countnumber: How many pay schedules were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The pay schedules.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many pay schedules Gusto has in all.

Example output

{
  "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 statusprocessing_statuseslist: Optional. Processed, unprocessed, or both. Gusto's default is processed.One or more of: processed, unprocessed.
Payroll typespayroll_typeslist: Optional. Gusto's default is regular payrolls only.One or more of: regular, off_cycle (Off-cycle), external.
Also includeincludelist: 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.
Fromstart_datedate: Optional. Payrolls on or after this date.
Toend_datedate: Optional. Payrolls on or before this date.
Ordersort_ordertext: Optional. Oldest or newest first.One of: asc (Oldest first), desc (Newest first).
Pagepagenumber: Optional. Fetch only this page. Leave blank to fetch every page (up to 2,000 records).At least 1.
Per pageper_pagenumber: Optional. How many records per page, 1 to 100.From 1 to 100.

Outputs

The payrolls.

countnumber: How many payrolls were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The payrolls.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many payrolls Gusto has in all.

Example output

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

Fromstart_datedate: Optional. Requests starting on or after this date.
Toend_datedate: Optional. Requests ending on or before this date.

Outputs

The time-off requests.

countnumber: How many time-off requests were returned.
has_moretrue/false: Whether more records exist than were returned.
itemslist: The time-off requests.
pagenumber: The page fetched, or empty when every page was fetched.
total_countnumber: How many time-off requests Gusto has in all.

Example output

{
  "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 IDemployee_idtextRequired: The employee's UUID, from 'List employees' or 'Create an employee'.
Last day of workeffective_datedateRequired: The employee's last day of work.
Pay final wages off-cyclerun_termination_payrolltrue/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.

activetrue/false: Whether the termination is in effect.
cancelabletrue/false: Whether it can still be cancelled.
effective_datetext: The last day of work.
employee_uuidtext: The employee's UUID.
run_termination_payrolltrue/false: Whether final wages go out in an off-cycle payroll.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.

Example output

{
  "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 IDcontractor_idtextRequired: The contractor's UUID, from 'List contractors' or 'Create a contractor'.
Contractor typecontractor_typetext: Optional. An individual person, or a business.One of: Individual, Business.
Wage typewage_typetext: Optional. Paid a fixed amount, or by the hour.One of: Fixed, Hourly.
Start datestart_datedate: Optional. Their first day.
Hourly ratehourly_ratetext: The hourly rate in dollars, e.g. 45.00. Required when paid by the hour.
First namefirst_nametext: The legal first name.
Last namelast_nametext: The legal last name.
Middle initialmiddle_initialtext: Optional.
Business namebusiness_nametext: The business's name (Business contractors).
EINeintext: Optional. The business's federal EIN.
Emailemailtext: Optional. Their email.
Work emailwork_emailtext: Optional. Their work email address.
File a new-hire reportfile_new_hire_reporttext: Optional. Whether Gusto files a state new-hire report.One of: yes, no.
Work statework_statetext: Optional. Two-letter US state code where they work, e.g. CA.
Activeis_activetext: Optional. No deactivates the contractor; Yes reactivates them.One of: yes, no.
Versionversiontext: 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.

addressobject: The contractor's address.
business_nametext: Business name (Business).
company_uuidtext: The company's UUID.
departmenttext: Department title.
department_uuidtext: Department UUID.
dismissal_datetext: Dismissal date, if dismissed.
eintext: EIN (Business).
emailtext: Email.
file_new_hire_reporttrue/false: Whether a new-hire report is filed.
first_nametext: First name (Individual).
has_eintrue/false: Whether an EIN is on file.
hourly_ratetext: Hourly rate, as text.
is_activetrue/false: Whether the contractor is active.
last_nametext: Last name (Individual).
middle_initialtext: Middle initial.
onboardedtrue/false: Whether onboarding is complete.
onboarding_statustext: Where onboarding stands.
payment_methodtext: Direct Deposit or Check.
start_datetext: Start date.
typetext: Individual or Business.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.
wage_typetext: Fixed or Hourly.
work_emailtext: Work email.
work_statetext: Work state.

Example output

{
  "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 IDemployee_idtextRequired: The employee's UUID, from 'List employees' or 'Create an employee'.
First namefirst_nametext: The legal first name.
Last namelast_nametext: The legal last name.
Middle initialmiddle_initialtext: Optional.
Preferred first namepreferred_first_nametext: Optional. The name they go by.
Personal emailemailtext: Optional. Their personal email.
Work emailwork_emailtext: Optional. Their work email address.
Date of birthdate_of_birthdate: Optional.
2% shareholdertwo_percent_shareholdertext: Optional. Whether they own 2% or more of the company (S corporations only).One of: yes, no.
Versionversiontext: 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_uuidtext: The company's UUID.
current_employment_statustext: full_time, part_time_..., variable or seasonal.
current_home_addressobject: Current home address (when included).
custom_fieldslist: Custom field values.
date_of_birthtext: Date of birth (YYYY-MM-DD).
departmenttext: Department title.
department_uuidtext: Department UUID.
emailtext: Personal email.
employee_codetext: The employee code.
first_nametext: First name.
flsa_statustext: FLSA classification.
has_ssntrue/false: Whether an SSN is on file.
hidden_ssntext: The SSN, masked.
hired_attext: Hire date.
jobslist: The employee's jobs.
last_nametext: Last name.
manager_uuidtext: The manager's UUID.
middle_initialtext: Middle initial.
onboardedtrue/false: Whether onboarding is complete.
onboarding_statustext: Where onboarding stands.
payment_methodtext: Direct Deposit or Check.
phonetext: Phone number.
preferred_first_nametext: Preferred first name.
terminatedtrue/false: Whether the employee is terminated.
terminationslist: The employee's terminations.
titletext: Job title.
two_percent_shareholdertrue/false: Whether they own 2% or more of an S-Corp.
uuidtext: The record's Gusto UUID.
versiontext: The record's current version, needed to update it.
warningslist: Gusto's warnings about the record.
work_emailtext: Work email.

Example output

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

ActionsCopy Anchor Link

Add people to a departmentCopy Anchor Link

Inputs

Outputs

Create a contractorCopy Anchor Link

Inputs

Outputs

Create a departmentCopy Anchor Link

Inputs

Outputs

Create a jobCopy Anchor Link

Inputs

Outputs

Create an employeeCopy Anchor Link

Inputs

Outputs

Get a contractorCopy Anchor Link

Inputs

Outputs

Get a payrollCopy Anchor Link

Inputs

Outputs

Get an employeeCopy Anchor Link

Inputs

Outputs

Get the companyCopy Anchor Link

Inputs

Outputs

List adminsCopy Anchor Link

Inputs

Outputs

List contractor paymentsCopy Anchor Link

Inputs

Outputs

List contractorsCopy Anchor Link

Inputs

Outputs

List departmentsCopy Anchor Link

Inputs

Outputs

List employeesCopy Anchor Link

Inputs

Outputs

List locationsCopy Anchor Link

Inputs

Outputs

List pay schedulesCopy Anchor Link

Inputs

Outputs

List payrollsCopy Anchor Link

Inputs

Outputs

List time-off requestsCopy Anchor Link

Inputs

Outputs

Terminate an employeeCopy Anchor Link

Inputs

Outputs

Update a contractorCopy Anchor Link

Inputs

Outputs

Update an employeeCopy Anchor Link

Inputs

Outputs

On this page

Actions

Add people to a department

Create a contractor

Create a department

Create a job

Create an employee

Get a contractor

Get a payroll

Get an employee

Get the company

List admins

List contractor payments

List contractors

List departments

List employees

List locations

List pay schedules

List payrolls

List time-off requests

Terminate an employee

Update a contractor

Update an employee