Rippling: Retrieve a specific worker

← rest_api operations · Get started · OpenAPI downloads

Contract 2026-10-28 · Operation rippling.rest_api.get_workers

Provider route: GET /workers/{id}/. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/rippling with npm, or alter-sdk-rippling with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { RipplingIntegration } from "@alter-ai/rippling";

async function execute(input: Parameters<RipplingIntegration["restApi"]["getWorkers"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new RipplingIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.restApi.getWorkers(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_rippling import RipplingIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = RipplingIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.rest_api.get_workers(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.id	string	Required within parent	Format: id
query	object	Optional	Additional keys: not allowed
query.expand	string	Optional

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root
__meta	object	Optional
__meta.redacted_fields	array	Optional
__meta.redacted_fields[]	Model	Each item	Expand Retrieve a report run — response body — meta redacted fields item
business_partners	array	Optional	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. Expandable field
business_partners[]	Model	Each item	Expand Retrieve a specific worker — response body — business partners item
business_partners_id	array	Optional	Worker’s assigned business partners unique identifiers. Returns an empty list ([]) if the worker has no business partners.
business_partners_id[]	string	Each item
citizenship	string	Optional	The countries that the worker has citizenship in. Known values: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IQ, IR, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RO, RU, RW, RE, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SY, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW
compensation	Model	Optional	Expand Retrieve a specific worker — response body — compensation
compensation_grade	object	Optional	The compensation grade assigned to the worker, if any.
compensation_grade.id	string	Optional	The compensation grade’s unique identifier.
compensation_grade.label	string	Optional	The compensation grade’s label.
compensation_id	string	Optional	The compensation package for the worker.
country	string	Optional	The worker’s country. Known values: AF, AX, AL, DZ, AS, AD, AO, AI, AQ, AG, AR, AM, AW, AU, AT, AZ, BS, BH, BD, BB, BY, BE, BZ, BJ, BM, BT, BO, BQ, BA, BW, BV, BR, IO, BN, BG, BF, BI, CV, KH, CM, CA, KY, CF, TD, CL, CN, CX, CC, CO, KM, CG, CD, CK, CR, CI, HR, CW, CY, CZ, DK, DJ, DM, DO, EC, EG, SV, GQ, ER, EE, SZ, ET, FK, FO, FJ, FI, FR, GF, PF, TF, GA, GM, GE, DE, GH, GI, GR, GL, GD, GP, GU, GT, GG, GN, GW, GY, HT, HM, VA, HN, HK, HU, IS, IN, ID, IQ, IR, IE, IM, IL, IT, JM, JP, JE, JO, KZ, KE, KI, KR, XK, KW, KG, LA, LV, LB, LS, LR, LY, LI, LT, LU, MO, MG, MW, MY, MV, ML, MT, MH, MQ, MR, MU, YT, MX, FM, MD, MC, MN, ME, MS, MA, MZ, MM, NA, NR, NP, NL, AN, NC, NZ, NI, NE, NG, NU, NF, MK, MP, NO, OM, PK, PW, PS, PA, PG, PY, PE, PH, PN, PL, PT, PR, QA, RO, RU, RW, RE, BL, SH, KN, LC, MF, PM, VC, WS, SM, ST, SA, SN, RS, SC, SL, SG, SX, SY, SK, SI, SB, SO, ZA, GS, SS, ES, LK, SD, SR, SJ, SE, CH, TW, TJ, TZ, TH, TL, TG, TK, TO, TT, TN, TR, TM, TC, TV, UG, UA, AE, GB, US, UM, UY, UZ, VU, VE, VN, VG, VI, WF, EH, YE, ZM, ZW
country_fields	Model	Optional	Expand Retrieve a specific worker — response body — country fields
created_at	string	Required within parent	Record creation date
custom_fields	array	Optional	Custom field values defined on the Employee object for this worker Expandable field
custom_fields[]	JSON	Each item	Additional keys: see wildcard field
custom_fields[].*	JSON	Additional keys
date_of_birth	string	Optional	The worker’s date of birth.
department	Model	Optional	Expand Retrieve a specific worker — response body — department
department_id	string	Optional	The worker’s assigned department.
employment_type	Model	Optional	Expand Retrieve a specific worker — response body — employment type
employment_type_id	string	Optional	The worker’s employment type.
end_date	string	Optional	The end date of the worker.
ethnicity	string	Optional	The identified ethnicity of the worker, if specified. Known values: 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, COLOURED, INDIAN, OTHER, PREFER_NOT_TO_SAY
gender	string	Optional	The gender of the worker, if specified. Known values: MALE, FEMALE, NONBINARY, UNDETERMINED, DIVERSE, DOES_NOT_APPLY, PREFER_NOT_TO_SAY
id	string	Required within parent	Identifier field
is_manager	boolean	Optional	Whether the worker is a manager
job_function	object	Optional	The worker’s job function. When expanded, this field requires `job-functions.read`. Expandable field
job_function.created_at	string	Required within parent	Record creation date
job_function.id	string	Required within parent	Identifier field
job_function.name	string	Optional	Displayed name of the job function
job_function.updated_at	string	Required within parent	Record update date
job_function_id	string	Optional	ID of the worker’s job function.
legal_entity	Model	Optional	Expand Retrieve a specific worker — response body — legal entity
legal_entity_id	string	Optional	The worker’s associated legal entity.
level	Model	Optional	Expand Retrieve a specific worker — response body — level
level_id	string	Optional	The level of the worker.
location	object	Optional	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.
location.type	string	Required within parent	The type of location. Known values: REMOTE, WORK
location.work_location_id	string	Required within parent	The work location, if the worker isn’t remote.
manager	Model	Optional	Expand Retrieve a specific worker — response body — manager The worker’s manager. Expandable field
manager_id	string	Optional	The worker’s manager.
number	JSON	Optional
number (anyOf 1)	integer	Alternative	The worker’s number within the organization.
number (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
original_start_date	string	Optional	The worker’s earliest start date across their employment history, excluding INIT roles.
overtime_exemption	string	Optional	The worker’s overtime exemption status. Known values: EXEMPT, NON_EXEMPT
pay_schedule_id	string	Optional	The ID of the pay schedule currently associated with the worker.
personal_email	string	Optional	The worker’s associated personal email address.
race	string	Optional	The identified race of the worker, if specified. Known values: BLACK, BROWN, CHINESE, EURASIAN, INDIAN, INDIGENOUS, MALAY, WHITE, YELLOW, NOT_INFORMED, OTHER
start_date	string	Optional	The start date of the worker.
status	string	Optional	The worker’s status within the organization. Known values: INIT, HIRED, ACCEPTED, ACTIVE, TERMINATED
teams	array	Optional	The worker’s assigned teams. Expandable field
teams[]	Model	Each item	Expand Update a team — response body — parent
teams_id	array	Optional	The worker’s assigned teams.
teams_id[]	string	Each item
termination_details	object	Optional	The details of the worker’s termination, if applicable.
termination_details.reason	string	Optional	This is a description that will be custom to each Rippling company.
termination_details.type	string	Optional	The termination type indicates whether the termination was voluntary or involuntary. Known values: VOLUNTARY, INVOLUNTARY, RETIREMENT, DEATH, ABANDONMENT, OFFER_DECLINED, RESCIND, RENEGE
title	string	Optional	The worker’s title.
title_effective_date	string	Optional	Title effective date
updated_at	string	Required within parent	Record update date
user	Model	Optional	Expand Retrieve a specific worker — response body — user
user_id	string	Optional	The worker’s associated user.
work_email	string	Optional	The worker’s associated work email address.
work_schedule	object	Optional	The worker’s scheduled working hours for each day of the week. Additional keys: see wildcard field
work_schedule.*	Model	Additional keys	Expand Retrieve a specific worker — response body — work schedule value

Referenced models: Retrieve a specific worker — response body — business partners item, Retrieve a report run — response body — meta redacted fields item, Update a team — response body — parent, Retrieve a specific worker — response body — work schedule value, Retrieve a specific worker — response body — manager, Retrieve a specific worker — response body — compensation, Retrieve a specific worker — response body — country fields, Retrieve a specific worker — response body — department, Retrieve a specific worker — response body — employment type, Retrieve a specific worker — response body — legal entity, Retrieve a specific worker — response body — level, Retrieve a specific worker — response body — user

Policy, approvals and errors

SDK function policy ID: rippling.rest_api.get_workers. Catalog operation: get-workers. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Required provider scopes: ["workers.read"]

Provider entitlements: ["API_Tier_1"]

Pinned headers: {"Rippling-Api-Version": "2024-08-01"}

Official provider source