GUgusto
Employees

Get employees of a company

Changed on

Get all of the employees, onboarding, active and terminated, for a given company.

Note: Compensation data (pay rate, payment unit, and related fields) represents sensitive employee pay information. When retrieving employee job data, these fields (rate, payment_unit, current_compensation_uuid, compensations) are only returned when the compensations:read scope is included. This allows you to access employee and job metadata without exposing pay rates.

scope: employees:read

get/v1/companies/{company_id}/employees

Request

Path parameters

company_idstring required

The UUID of the company

Query parameters

location_uuidstring

Filter employees by a specific primary work location

payroll_uuidstring

Filter employees by a specific payroll

search_termstring

A string to search for in the object's names

sort_bystring
Example:created_at:asc

Sort employees by a given field. Cannot be used with search_term. Append :asc or :desc to specify direction (e.g., name:desc). Defaults to ascending.

includestring[]

Include the requested attribute(s) in each employee response. Multiple options are comma separated.

onboardedboolean

Filters employees by those who have completed onboarding

onboarded_activeboolean

Filters employees who are ready to work (onboarded AND active today)

terminatedboolean

Filters employees by those who have been or are scheduled to be terminated

terminated_todayboolean

Filters employees by those who have been terminated and whose termination is in effect today (excludes active and scheduled to be terminated)

uuidsstring[]

Optional subset of employees to fetch.

pageinteger

The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.

perinteger

Number of objects per page. For majority of endpoints will default to 25

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Response

successful

uuidstring required

The UUID of the employee in Gusto.

first_namestring required
middle_initialstring nullable
last_namestring required
emailstring nullable

The personal email address of the employee. This is provided to support syncing users between our system and yours. You may not use this email address for any other purpose (e.g. marketing).

company_uuidstring

The UUID of the company the employee is employed by.

manager_uuidstring nullable

The UUID of the employee's manager.

versionstring

The current version of the employee. See the versioning guide for information on how to use this field.

departmentstring nullable

The employee's department in the company.

terminatedboolean

Whether the employee is terminated.

two_percent_shareholderboolean nullable

Whether the employee is a two percent shareholder of the company. This field only applies to companies with an S-Corp entity type.

work_emailstring nullable

The work email address of the employee. This is provided to support syncing users between our system and yours. You may not use this email address for any other purpose (e.g. marketing).

onboardedboolean

Whether the employee has completed onboarding.

onboarding_status'onboarding_completed' | 'admin_onboarding_incomplete' | 'self_onboarding_pending_invite' | 'self_onboarding_invited' | 'self_onboarding_invited_started' | 'self_onboarding_invited_overdue' | 'self_onboarding_completed_by_employee' | 'self_onboarding_awaiting_admin_review' nullable

The current onboarding status of the employee

date_of_birthstring nullable
has_ssnboolean

Indicates whether the employee has an SSN in Gusto.

ssnstring

Deprecated. This field always returns an empty string.

phonestring nullable
preferred_first_namestring nullable
payment_method'Direct Deposit' | 'Check'

The employee's payment method

current_employment_status'full_time' | 'part_time_under_twenty_hours' | 'part_time_twenty_plus_hours' | 'variable' | 'seasonal' nullable

The current employment status of the employee. Full-time employees work 30+ hours per week. Part-time employees are split into two groups: those that work 20-29 hours a week, and those that work under 20 hours a week. Variable employees have hours that vary each week. Seasonal employees are hired for 6 months of the year or less.

historicalboolean
employee_codestring

The short format code of the employee

department_uuidstring nullable

The UUID of the department the employee is under

titlestring
hired_atstring date

The date when the employee was hired to the company

hidden_ssnstring
flsa_status'Exempt' | 'Salaried Nonexempt' | 'Nonexempt' | 'Owner' | 'Commission Only Exempt' | 'Commission Only Nonexempt'

The FLSA status for this compensation. Salaried ('Exempt') employees are paid a fixed salary every pay period. Salaried with overtime ('Salaried Nonexempt') employees are paid a fixed salary every pay period, and receive overtime pay when applicable. Hourly ('Nonexempt') employees are paid for the hours they work, and receive overtime pay when applicable. Commissioned employees ('Commission Only Exempt') earn wages based only on commission. Commissioned with overtime ('Commission Only Nonexempt') earn wages based on commission, and receive overtime pay when applicable. Owners ('Owner') are employees that own at least twenty percent of the company.

applicable_tax_idsnumber[]
partner_portal_invitation_sentboolean nullable

Whether an external partner portal invitation webhook has been sent for this employee. Only included when the include param has the portal_invitations value set.

company_namestring

The name of the company the employee is associated with. Only included when the include param has the company_name value set.

Example response

[
  {
    "eligible_paid_time_off": [
      {
        "accrual_unit": "Hour",
        "accrual_method": "unlimited",
        "accrual_period": "Year"
      }
    ],
    "current_home_address": {
      "street_1": "412 Kiera Stravenue",
      "street_2": "Suite 391",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94107",
      "country": "USA",
      "active": true,
      "uud": "sample-uuid-123231"
    },
    "all_home_addresses": [
      {
        "street_1": "412 Kiera Stravenue",
        "street_2": "Suite 391",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94107",
        "country": "USA",
        "active": true,
        "uud": "sample-uuid-123231",
        "effective_date": "2024-01-01"
      }
    ]
  }
]

Changes

  • f98575fa2a5eRevision changes
    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • info

      added to the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status