Skip to content

Rippling: List app users

Rippling restApi.listAppUsers: arguments, response, policy and SDK examples.

← Rest API operations · Get started

Operation rippling.rest_api.list_app_users

Provider route: GET /app-users/. Alter supplies the connection’s credentials and routing.

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"]["listAppUsers"]>[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.listAppUsers(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.list_app_users(arguments)
result = await call.wait()
return result.body_json()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
queryobjectOptionalAdditional keys: not allowed
query.filterstringOptional
query.expandstringOptional
query.order_bystringOptional
query.limitintegerOptionalDefault: 50
Maximum: 100
Minimum: 1
query.cursorstringOptional

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

FieldTypePresenceDescription and constraints
$objectRoot
__metaModelOptionalExpand List Sites — response body — meta
next_linkstringOptionalA link to the next page of responses.
Format: uri
resultsarrayOptional
results[]ModelEach itemExpand List app users — response body — results item

Referenced models: List app users — response body — results item, List Sites — response body — meta

21 more schemas are linked from the tables above, on the schema pages.

List app users — response body — results item
FieldTypePresenceDescription and constraints
$objectRoot
Maps a Rippling worker (if any) to their user account in a third-party
app (e.g. Slack, Jira, GitHub). Sourced from SpokeUser records.

Includes orphan accounts — third-party app accounts with no matching
Rippling worker (`worker_id=None`, `match_state=NOT_MATCHED`). These are
the primary signal for IT-admin triage. Uses `BaseResourceDTO` rather
than `BaseEmployeeResourceDTO` so the platform's role-based auto-filter
does not silently drop orphans for non-admin tokens. Company scoping is
enforced explicitly in `AppUsersAPIViewSet.get_queryset`; the `app-users.read`
scope is the access gate.

Resource name aligns with how the product surfaces these in the UI
("Slack account", "GitHub account") and matches the equivalent concept
in Okta's IAM API (AppUser).

Designed for point lookups: list endpoint requires at least one filter
on `worker_id` or `spoke_user_identifier` to prevent bulk enumeration of the
org's identity graph across connected apps.

`spoke_user_identifier` reads `SpokeUser.spokeId` — the user identifier
stored for the third-party account. Depending on the integration, this may
be an email, username, account handle, or app-specific user id.
app_display_namestringOptionalHuman-readable display name for the third-party app (e.g. 'Slack', 'GitHub'). Sourced from the customer-configured SpokeOwner.app_display_name; falls back to a title-cased app handle when the customer hasn't set one.
app_handlestringOptionalMachine-readable identifier for the third-party app (e.g. 'slack', 'jira', 'asana'). Stable across the App Shop catalog.
created_atstringRequired within parentRecord creation date
external_emailstringOptionalThe user's email address in the third-party app, if known. Null when the app does not expose an email or Rippling did not capture one.
external_usernamestringOptionalThe user's display name in the third-party app, if known. Null when the app does not surface a separate username.
idstringRequired within parentIdentifier field
match_statestringOptionalWhether this third-party account has been matched to a Rippling worker.
Known values: MATCHED, NOT_MATCHED, IGNORED
push_statestringOptionalProvisioning lifecycle state of this account in the third-party app.
Known values: INIT, EMPLOYEE_CONFIRMATION_PENDING, EMPLOYEE_CONFIRMATION_ACCEPTED, EMPLOYEE_CONFIRMATION_REJECTED, INVITE_PENDING, INVITE_CONFIRMED, INVITE_FAILED, CREATE_PENDING, CREATE_CONFIRMED, CREATE_FAILED, DELETE_PENDING, DELETE_CONFIRMED, DELETE_FAILED, SUSPEND_PENDING, SUSPEND_CONFIRMED, SUSPEND_FAILED
spoke_user_identifierstringOptionalIdentifier for the user's account in the third-party app workspace. Depending on the integration, this may be an email, username, account handle, or app-specific user id.
updated_atstringRequired within parentRecord update date
workerModelOptionalExpand Retrieve a specific app user — response body — worker
worker_idstringOptionalID of the Rippling worker associated with this external app account.

Referenced models: Retrieve a specific app user — response body — worker

List Sites — response body — meta
FieldTypePresenceDescription and constraints
$objectRootA list of redacted fields.
redacted_fieldsarrayOptional
redacted_fields[]objectEach item
redacted_fields[].namestringOptionalThe name for the redacted field
redacted_fields[].reasonstringOptionalThe reason for the redaction
Retrieve a specific worker — response body — business partners item
FieldTypePresenceDescription and constraints
$objectRoot
business_partner_groupobjectOptionalBusiness partner group the business partner is a part of

Expandable field
business_partner_group.created_atstringRequired within parentRecord creation date
business_partner_group.default_business_partnerModelOptionalExpand Retrieve a specific worker — response body — manager
Optional default business partner worker to whom all employees will be mapped if not explicitly mapped to a business partner in the group.

Expandable field
business_partner_group.default_business_partner_idstringOptionalId of Optional default business partner worker to whom all employees will be mapped if not explicitly mapped to a business partner in the group.
business_partner_group.domainstringOptionalType of business partner group
Known values: HR, IT, FINANCE, RECRUITING, OTHER
business_partner_group.idstringRequired within parentIdentifier field
business_partner_group.namestringRequired within parentName used to identify business partner group
business_partner_group.updated_atstringRequired within parentRecord update date
business_partner_group_idstringRequired within parentIdentifier of business partner group the business parter is a part of
client_groupModelOptionalExpand Create a new business partner — response body — client group
client_group_idstringOptionalIdentifier of group of workers associated with the business partner
client_group_member_countJSONOptional
client_group_member_count (anyOf 1)integerAlternativeNumber of workers associated with the business partner
client_group_member_count (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
created_atstringRequired within parentRecord creation date
idstringRequired within parentIdentifier field
updated_atstringRequired within parentRecord update date
workerModelOptionalExpand Retrieve a specific worker — response body — manager
Worker who is the business partner

Expandable field
worker_idstringRequired within parentIdentifier of worker who is the business partner

Referenced models: Retrieve a specific worker — response body — manager, Create a new business partner — response body — client group

Update a team — response body — parent
FieldTypePresenceDescription and constraints
$objectRoot
created_atstringRequired within parentRecord creation date
idstringRequired within parentIdentifier field
namestringRequired within parentThe name of the team.
parentModelOptionalExpand Update a team — response body — parent
The parent team

Expandable field
parent_idstringOptionalThe parent team
updated_atstringRequired within parentRecord update date

Referenced models: Update a team — response body — parent

Retrieve a specific worker — response body — work schedule value
FieldTypePresenceDescription and constraints
$objectRootThe scheduled working hours for a day of the week.
hoursJSONOptional
hours (anyOf 1)numberAlternativeThe number of scheduled working hours for the day.
hours (anyOf 2)stringAlternativePattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
Retrieve a specific worker — response body — country fields
FieldTypePresenceDescription and constraints
$objectRootCountry level fields for the worker.
caobjectOptionalCountry-wise regional fields for Canada
ca.sinstringOptionalSocial Insurance Number (SIN) for Canada employees.
nzobjectOptionalCountry-wise regional fields for New Zealand
nz.ird_numberstringOptionalInland Revenue Department (IRD) number for New Zealand employees.
usobjectOptionalCountry-wise regional fields for USA
us.ssnstringOptionalSocial Security Number (SSN) for US employees.
Retrieve a specific worker — response body — department
FieldTypePresenceDescription and constraints
$objectRootThe worker's assigned department.

Expandable field
created_atstringRequired within parentRecord creation date
department_hierarchyarrayOptionalList of departments in the department hierarchy. Refer department_hierarchy_ids for department hierarchy order.

Expandable field
department_hierarchy[]ModelEach itemExpand Update a department — response body — parent
department_hierarchy_idarrayOptionalThe identifier of departments in the department hierarchy ordered from parent department to child department.
department_hierarchy_id[]stringEach item
idstringRequired within parentIdentifier field
namestringRequired within parentThe name of the department.
parentModelOptionalExpand Update a department — response body — parent
The parent department.

Expandable field
parent_idstringOptionalThe parent department.
reference_codestringOptionalReference code of the department.
updated_atstringRequired within parentRecord update date

Referenced models: Update a department — response body — parent

Retrieve a specific user — response body — emails item
FieldTypePresenceDescription and constraints
$objectRoot
displaystringOptionalThe display value of the email address.
typestringOptionalThe classification of the email.
Known values: HOME, WORK, OTHER
valuestringOptionalA valid email address.

SDK function policy ID: rippling.rest_api.list_app_users. Catalog operation: list-app-users. 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: ["app-users.read"]

Provider entitlements: ["API_Tier_1"]

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

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.