# List workers

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Every page is available as Markdown by adding .md to its URL.

> A list of workers.

Source: https://developer.rippling.com/documentation/rest-api/reference/list-workers

`GET https://rest.ripplingapis.com/workers/`

A list of workers.
 - Requires: `API Tier 1`
 - Filterable fields: `status`, `work_email`, `user_id`, `created_at`, `updated_at`
 - Expandable fields: `user`, `manager`, `legal_entity`, `employment_type`, `compensation`, `department`, `teams`, `level`, `job_function`, `custom_fields`, `business_partners`
 - Sortable fields: `id`, `created_at`, `updated_at`

- OAuth scopes: `workers.read`

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `filter` | query | string | No |  |
| `expand` | query | string | No |  |
| `order_by` | query | string | No |  |
| `limit` | query | integer | No | The maximum number of results to return. Defaults to 50. Maximum is 100. |
| `cursor` | query | string | No |  |

## Responses

### 200: Successful response

- `__meta` (object): A list of redacted fields.
  - `redacted_fields` (array of object)
    - `name` (string): The name for the redacted field
    - `reason` (string): The reason for the redaction
- `results` (array of object)
  - `id` (string, required): Identifier field
  - `created_at` (string, required): Record creation date
  - `updated_at` (string, required): Record update date
  - `user_id` (string): The worker's associated user.
  - `user` (object): The worker's associated user. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `active` (boolean): Whether the user is able to access company resources, typically when they are in actively engaged with the company and not after off-boarding.
    - `username` (string): The unique identifier across Rippling used by the User for direct authentication into their associated company. Globally unique.
    - `name` (object): The user's name.
    - `display_name` (string): The display name of the user using either the concatenated preferred given and family name or username depending on availability.
    - `emails` (array of object): The user's email addresses.
    - `phone_numbers` (array of object): The user's phone numbers.
    - `addresses` (array of object): The user's addresses.
    - `photos` (array of object): The user's photos.
    - `preferred_language` (string): The User's preferred written or spoken language in the same format of the HTTP Accept-Language header, pursuant to Section 5.3.5 of RFC7231.
    - `locale` (string): The User's default location for purposes of localization of currency, date time format, or numerical representations pursuant to RFC5646.
    - `timezone` (string): The User's current time zone in IANA database Olson format
    - `number` (string): The permanent profile number of the user.
  - `is_manager` (boolean): Whether the worker is a manager
  - `manager_id` (string): The worker's manager.
  - `manager` (object): The worker's manager. Expandable field
  - `legal_entity_id` (string): The worker's associated legal entity.
  - `legal_entity` (object): The worker's associated legal entity. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `tax_identifier` (string): The tax identifier for the legal entity.
    - `country` (object): The country the legal entity is based in.
    - `legal_name` (string): The legal name of the legal entity.
    - `entity_level` (string): The legal entity's level in a hierarchy. * `PARENT`: The legal entity is considered the ultimate holding entity. * `SUBSIDIARY`: The legal entity is considered a subsidiary, fully or partially held by another. * `BRANCH`: The legal entity… One of: `PARENT`, `SUBSIDIARY`, `BRANCH`.
    - `registration_date` (string): The registration date of the entity.
    - `mailing_address` (object): The mailing address of the legal entity.
    - `physical_address` (object): The physical address of the legal entity, if it differs from the mailing address.
    - `parent_id` (string): The parent legal entity.
    - `parent` (object): The parent legal entity. Expandable field
    - `management_type` (string): The legal entity management type in the case of an employer of record (EOR) or professional employment organization (PEO). * `PEO`: The legal entity is considered a Professional Employment Organization (PEO). * `EOR`: The legal entity is c… One of: `PEO`, `EOR`, `COR`.
    - `company_id` (string): The company or organization associated with the legal entity
    - `company` (object): The company or organization associated with the legal entity Expandable field
  - `country` (string): The worker's country. One of: `AF`, `AX`, `AL`, `DZ`, `AS`, `AD`, `AO`, `AI`, `AQ`, `AG`, ….
  - `start_date` (string): The start date of the worker.
  - `end_date` (string): The end date of the worker.
  - `number` (integer): The worker's number within the organization.
  - `work_email` (string): The worker's associated work email address.
  - `personal_email` (string): The worker's associated personal email address.
  - `status` (string): The worker's status within the organization. One of: `INIT`, `HIRED`, `ACCEPTED`, `ACTIVE`, `TERMINATED`.
  - `location` (object): The location that the worker is mapped to for tax purposes. In the case that a worker is remote, the location's type is remote.
    - `type` (string, required): The type of location. One of: `REMOTE`, `WORK`.
    - `work_location_id` (string, required): The work location, if the worker isn't remote.
  - `employment_type_id` (string): The worker's employment type.
  - `employment_type` (object): The worker's employment type. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `label` (string, required): The display label of the employment type.
    - `name` (string): The name of the employment type for non-custom employment types.
    - `type` (string): The classification of the worker by the company. * `CONTRACTOR`: Contractors are self-employed workers who provide services on a short-term or per-project basis and are not eligible for tax-withholding or benefits. * `EMPLOYEE`: Employees… One of: `CONTRACTOR`, `EMPLOYEE`.
    - `compensation_time_period` (string): The compensation period for the employment type. * `SALARIED`: Employees that are paid a fixed amount per year. * `HOURLY`: Employees that are paid a wage per hour worked. One of: `HOURLY`, `SALARIED`.
    - `amount_worked` (string): The amount worked for the employment type. * `FULL-TIME`: Full-time is at least 30 hours per week. Full-time workers will typically be eligible for benefits. * `PART-TIME`: Part-time is less than 30 hours per week. These workers may be eli… One of: `PART-TIME`, `FULL-TIME`, `TEMPORARY`.
  - `gender` (string): The gender of the worker, if specified. One of: `MALE`, `FEMALE`, `NONBINARY`, `UNDETERMINED`, `DIVERSE`, `DOES_NOT_APPLY`, `PREFER_NOT_TO_SAY`.
  - `date_of_birth` (string): The worker's date of birth.
  - `race` (string): The identified race of the worker, if specified. One of: `BLACK`, `BROWN`, `CHINESE`, `EURASIAN`, `INDIAN`, `INDIGENOUS`, `MALAY`, `WHITE`, `YELLOW`, `NOT_INFORMED`, ….
  - `ethnicity` (string): The identified ethnicity of the worker, if specified. One of: `HISPANIC_OR_LATINO`, `WHITE`, `BLACK_OR_AFRICAN_AMERICAN`, `NATIVE_HAWAIIAN_OR_OTHER_PACIFIC_ISLANDER`, `ASIAN`, `AMERICAN_INDIAN_OR_ALASKA_NATIVE`, `TWO_OR_MORE_RACES`, `MIDDLE_EASTERN_OR_NORTH_AFRICAN`, `DECLINE_TO_SELF_IDENTIFY`, `AFRICAN`, ….
  - `citizenship` (string): The countries that the worker has citizenship in. One of: `AF`, `AX`, `AL`, `DZ`, `AS`, `AD`, `AO`, `AI`, `AQ`, `AG`, ….
  - `compensation_id` (string): The compensation package for the worker.
  - `compensation` (object): The compensation package for the worker. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `worker_id` (string): The worker's ID.
    - `worker` (object): The worker's details. Expandable field
    - `annual_compensation` (object): The worker's annual compensation. This calculation assumes 40-hour work weeks for workers with an hourly wage.
    - `annual_salary_equivalent` (object): The worker's annual salary equivalent, for insurance purposes. It will be equal to the worker's annual compensation, except for owners that are receiving no cashcompensation.
    - `hourly_wage` (object): The worker's hourly wage. This calculation assumes 40-hour work weeks for workers with fixed compensation.
    - `monthly_compensation` (object): The worker's monthly compensation. This calculation assumes 40-hour work weeks for workers with an hourly wage.
    - `on_target_commission` (object): The worker's on-target commission.
    - `relocation_reimbursement` (object): The worker's hourly wage. This calculation assumes 40-hour work weeks for workers with fixed compensation.
    - `signing_bonus` (object): The worker's signing bonus.
    - `target_annual_bonus` (object): The worker's target annual bonus amount.
    - `weekly_compensation` (object): The worker's weekly compensation. This calculation assumes 40-hour work weeks for workers with an hourly wage.
    - `target_annual_bonus_percent` (number): The worker's target annual bonus as a percent of annual compensation.
    - `bonus_schedule` (string): The worker's bonus schedule.
    - `payment_type` (string): The payment type for an worker's compensation.
    - `payment_terms` (string): The payment terms for an worker's compensation.
    - `salary_effective_date` (string): Salary effective date
  - `overtime_exemption` (string): The worker's overtime exemption status. One of: `EXEMPT`, `NON_EXEMPT`.
  - `department_id` (string): The worker's assigned department.
  - `department` (object): The worker's assigned department. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `name` (string, required): The name of the department.
    - `parent_id` (string): The parent department.
    - `parent` (object): The parent department. Expandable field
    - `reference_code` (string): Reference code of the department.
    - `department_hierarchy_id` (array of string): The identifier of departments in the department hierarchy ordered from parent department to child department.
    - `department_hierarchy` (array): List of departments in the department hierarchy. Refer department_hierarchy_ids for department hierarchy order. Expandable field
  - `teams_id` (array of string): The worker's assigned teams.
  - `teams` (array of object): The worker's assigned teams. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `parent_id` (string): The parent team
    - `parent` (object): The parent team Expandable field
    - `name` (string, required): The name of the team.
  - `title` (string): The worker's title.
  - `title_effective_date` (string): Title effective date
  - `level_id` (string): The level of the worker.
  - `level` (object): The level of the worker. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `name` (string, required): The name of the level. Must be unique within the company or organization.
    - `parent_id` (string): The parent level.
    - `parent` (object): The parent level. Expandable field
    - `global_level` (integer): Global level is used to track the seniority of levels. The higher up a level is placed on the page, the more senior and higher-ranked the level. Global level is used in workflows, policies, and reports that use the level attribute (e.g., y…
    - `description` (string): The description of the level.
    - `scope_of_responsibilities` (string): The scope of responsibilities for the level.
    - `experience_requirements` (string): The experience requirements for the level.
    - `rank` (integer): The rank of the level within its track.
    - `track_id` (string): The track associated with the level. Required during creation. Include global_level when changing it.
    - `track` (object): The track associated with the level, if it's not a global level. Expandable field
  - `job_function_id` (string): ID of the worker's job function.
  - `job_function` (object): The worker's job function. When expanded, this field requires `job-functions.read`. Expandable field
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `name` (string): Displayed name of the job function
  - `termination_details` (object): The details of the worker's termination, if applicable.
    - `type` (string): The termination type indicates whether the termination was voluntary or involuntary. One of: `VOLUNTARY`, `INVOLUNTARY`, `RETIREMENT`, `DEATH`, `ABANDONMENT`, `OFFER_DECLINED`, `RESCIND`, `RENEGE`.
    - `reason` (string): This is a description that will be custom to each Rippling company.
  - `pay_schedule_id` (string): The ID of the pay schedule currently associated with the worker.
  - `work_schedule` (object): The worker's scheduled working hours for each day of the week.
  - `compensation_grade` (object): The compensation grade assigned to the worker, if any.
    - `id` (string): The compensation grade's unique identifier.
    - `label` (string): The compensation grade's label.
  - `original_start_date` (string): The worker's earliest start date across their employment history, excluding INIT roles.
  - `custom_fields` (array): Custom field values defined on the Employee object for this worker Expandable field
  - `country_fields` (object): Country level fields for the worker.
    - `us` (object): Country-wise regional fields for USA
    - `ca` (object): Country-wise regional fields for Canada
    - `nz` (object): Country-wise regional fields for New Zealand
  - `business_partners_id` (array of string): Worker's assigned business partners unique identifiers. Returns an empty list ([]) if the worker has no business partners.
  - `business_partners` (array of object): Worker's assigned business partners. This field is only populated when explicitly requested via the expand parameter (e.g., ?expand=business_partners). When expanded, returns an empty list ([]) if the worker has no business partners. Expan…
    - `id` (string, required): Identifier field
    - `created_at` (string, required): Record creation date
    - `updated_at` (string, required): Record update date
    - `business_partner_group_id` (string, required): Identifier of business partner group the business parter is a part of
    - `business_partner_group` (object): Business partner group the business partner is a part of Expandable field
    - `worker_id` (string, required): Identifier of worker who is the business partner
    - `worker` (object): Worker who is the business partner Expandable field
    - `client_group_id` (string): Identifier of group of workers associated with the business partner
    - `client_group` (object): Group of workers associated with the business partner Expandable field
    - `client_group_member_count` (integer): Number of workers associated with the business partner
- `next_link` (string, uri): A link to the next page of responses.