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.
Call through Alter
Section titled “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"]["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 osfrom alter_sdk import Appfrom 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()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
query | object | Optional | Additional keys: not allowed |
query.filter | string | Optional | |
query.expand | string | Optional | |
query.order_by | string | Optional | |
query.limit | integer | Optional | Default: 50 Maximum: 100 Minimum: 1 |
query.cursor | string | Optional |
Response
Section titled “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 | Model | Optional | Expand List Sites — response body — meta |
next_link | string | Optional | A link to the next page of responses. Format: uri |
results | array | Optional | |
results[] | Model | Each item | Expand List app users — response body — results item |
Referenced models: List app users — response body — results item, List Sites — response body — meta
Schemas
Section titled “Schemas”21 more schemas are linked from the tables above, on the schema pages.
List app users — response body — results item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | 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_name | string | Optional | Human-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_handle | string | Optional | Machine-readable identifier for the third-party app (e.g. 'slack', 'jira', 'asana'). Stable across the App Shop catalog. |
created_at | string | Required within parent | Record creation date |
external_email | string | Optional | The 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_username | string | Optional | The user's display name in the third-party app, if known. Null when the app does not surface a separate username. |
id | string | Required within parent | Identifier field |
match_state | string | Optional | Whether this third-party account has been matched to a Rippling worker. Known values: MATCHED, NOT_MATCHED, IGNORED |
push_state | string | Optional | Provisioning 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_identifier | string | Optional | Identifier 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_at | string | Required within parent | Record update date |
worker | Model | Optional | Expand Retrieve a specific app user — response body — worker |
worker_id | string | Optional | ID 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A list of redacted fields. |
redacted_fields | array | Optional | |
redacted_fields[] | object | Each item | |
redacted_fields[].name | string | Optional | The name for the redacted field |
redacted_fields[].reason | string | Optional | The reason for the redaction |
Retrieve a specific worker — response body — business partners item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
business_partner_group | object | Optional | Business partner group the business partner is a part of Expandable field |
business_partner_group.created_at | string | Required within parent | Record creation date |
business_partner_group.default_business_partner | Model | Optional | Expand 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_id | string | Optional | Id 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.domain | string | Optional | Type of business partner group Known values: HR, IT, FINANCE, RECRUITING, OTHER |
business_partner_group.id | string | Required within parent | Identifier field |
business_partner_group.name | string | Required within parent | Name used to identify business partner group |
business_partner_group.updated_at | string | Required within parent | Record update date |
business_partner_group_id | string | Required within parent | Identifier of business partner group the business parter is a part of |
client_group | Model | Optional | Expand Create a new business partner — response body — client group |
client_group_id | string | Optional | Identifier of group of workers associated with the business partner |
client_group_member_count | JSON | Optional | |
client_group_member_count (anyOf 1) | integer | Alternative | Number of workers associated with the business partner |
client_group_member_count (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
created_at | string | Required within parent | Record creation date |
id | string | Required within parent | Identifier field |
updated_at | string | Required within parent | Record update date |
worker | Model | Optional | Expand Retrieve a specific worker — response body — manager Worker who is the business partner Expandable field |
worker_id | string | Required within parent | Identifier 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
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
created_at | string | Required within parent | Record creation date |
id | string | Required within parent | Identifier field |
name | string | Required within parent | The name of the team. |
parent | Model | Optional | Expand Update a team — response body — parent The parent team Expandable field |
parent_id | string | Optional | The parent team |
updated_at | string | Required within parent | Record update date |
Referenced models: Update a team — response body — parent
Retrieve a specific worker — response body — work schedule value
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The scheduled working hours for a day of the week. |
hours | JSON | Optional | |
hours (anyOf 1) | number | Alternative | The number of scheduled working hours for the day. |
hours (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
Retrieve a specific worker — response body — country fields
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Country level fields for the worker. |
ca | object | Optional | Country-wise regional fields for Canada |
ca.sin | string | Optional | Social Insurance Number (SIN) for Canada employees. |
nz | object | Optional | Country-wise regional fields for New Zealand |
nz.ird_number | string | Optional | Inland Revenue Department (IRD) number for New Zealand employees. |
us | object | Optional | Country-wise regional fields for USA |
us.ssn | string | Optional | Social Security Number (SSN) for US employees. |
Retrieve a specific worker — response body — department
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The worker's assigned department. Expandable field |
created_at | string | Required within parent | Record creation date |
department_hierarchy | array | Optional | List of departments in the department hierarchy. Refer department_hierarchy_ids for department hierarchy order. Expandable field |
department_hierarchy[] | Model | Each item | Expand Update a department — response body — parent |
department_hierarchy_id | array | Optional | The identifier of departments in the department hierarchy ordered from parent department to child department. |
department_hierarchy_id[] | string | Each item | |
id | string | Required within parent | Identifier field |
name | string | Required within parent | The name of the department. |
parent | Model | Optional | Expand Update a department — response body — parent The parent department. Expandable field |
parent_id | string | Optional | The parent department. |
reference_code | string | Optional | Reference code of the department. |
updated_at | string | Required within parent | Record update date |
Referenced models: Update a department — response body — parent
Retrieve a specific user — response body — emails item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
display | string | Optional | The display value of the email address. |
type | string | Optional | The classification of the email. Known values: HOME, WORK, OTHER |
value | string | Optional | A valid email address. |
Policy, approvals and errors
Section titled “Policy, approvals and errors”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"}