Rippling SDK: get started

Use an ordinary App for a payroll product, or an Agent when the workload needs agent identity. Alter builds native Rippling requests from a reviewed contract and applies connection authorization, policy, approvals and audit records.

Install

npm install @alter-ai/sdk @alter-ai/rippling
# Python (installs core automatically)
pip install alter-sdk-rippling

The provider package includes only Rippling types and response schemas and pins its contract version.

Connect and call

Configure Rippling OAuth using the App Shop listing’s app name and credentials. Declare the listing’s scopes, including companies.read for connection identity and the scopes the application’s workflows require. Keep each customer’s grant ID after Connect consent. Rippling sets permissions on the listing; passing more scope names to Alter does not grant additional access.

Alternatively, create a Rippling managed secret with a company API token and keep its grant ID. Pass that same ID to the provider package or CLI shown below. The backend uses the stored template identity and host allowlist; both connection types receive policy, approvals, and audit. Configure allowed hosts for the APIs you use. A V2 company token normally uses rest.ripplingapis.com; OAuth-only endpoints and product permissions remain subject to Rippling’s restrictions. The portal’s managed-secret detail page also shows the complete versioned operation catalog.

import { App } from "@alter-ai/sdk";
import { RipplingIntegration } from "@alter-ai/rippling";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const rippling = new RipplingIntegration(app, { grantId: process.env.RIPPLING_GRANT_ID! });
  const result = await (await rippling.restApi.listWorkers({ query: { limit: 50 } })).wait();
  console.log(result.bodyJson());
} finally {
  await app.close();
}

from alter_sdk import App
from alter_sdk_rippling import RipplingIntegration

async def list_workers(api_key: str, grant_id: str):
    async with App(api_key=api_key) as app:
        rippling = RipplingIntegration(app, {"grant_id": grant_id})
        call = await rippling.rest_api.list_workers({"query": {"limit": 50}})
        result = await call.wait()
        return result.body_json()

Complete pinned inventory

Contract 2026-10-28 contains 480 documented variants across 12 namespaces, mapping to 473 distinct governed routes. It includes REST, legacy base and employee APIs, payroll, global payroll, time and attendance, company, recruiting, job board, reports, developer portal and the V1 archive. The API reference links every SDK method to its complete input fields, response models, TypeScript and Python examples, policy identity, and source limitations.

Browse namespaces under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specifications. Each namespace has its own specification because several publish different models for the same native route. Schemas are also available in the Developer Portal and through alter integrations operations rippling --version 2026-10-28.

Provider SDK 0.4.0 pins contract 2026-10-28, in which rest_api.create_hires accepts a pending hire without a name, start date or compensation: Rippling creates it and reports it incomplete with missing_required_fields, and the SDK returns that result instead of raising. Each hire still needs employment.title, employment.employment_type_id and work_location.country_code. Contract 2026-10-27 (SDK 0.3.1) added custom-object list views, record details, record-detail reference options and related records, and search / order_by on the custom-object record query. Contract 2026-10-26 (SDK 0.2.0) added the permission-profile membership read and updated hiring, workflow, function, custom-object and payment models. The documented custom-object write receipt accepts its required id even though upstream omits it from the closed object’s properties. Contracts 2026-10-27, 2026-10-26 and 2026-10-21 remain available for existing clients and pending approvals.

alter integrations execute rippling rippling.rest_api.list_workers \
  --version 2026-10-28 --grant "$RIPPLING_GRANT_ID" \
  --input '{"query":{"limit":50}}' --wait

Arguments use native path, query, headers and body containers. REST methods pin Rippling-Api-Version: 2024-08-01. The server selects the provider host and preserves legacy server path prefixes; caller input cannot override the destination or bearer token. Missing preview endpoints fail explicitly instead of falling back to production. Normal Rippling test-company installations use the existing App Shop connection flow.

Provider entitlements, listing approval, geography, product access and legacy availability still apply. Native Idempotency-Key input is exposed only where documented. Alter does not automatically replay writes or follow pagination links. Pass the returned cursor to the next list call.

Responses and source limitations

The SDK preserves additive fields, exact decimals and integers outside JavaScript’s safe range. HTTP 204 decodes as null / None; XML and other binary responses remain available through bodyBytes() / body_bytes() or the CLI’s --output-file. Provider failures retain their original body for diagnosis and reconciliation.

Twelve circular schema placeholders are resolved from complete definitions in the same pinned reference. Narrow response overrides reconcile ten published examples with contradictory machine schemas, including legacy list/object variants, nullability and missing required fields. All 71 official successful JSON response examples are tested. These corrections do not weaken request validation.

Legacy time-entry creation accepts both documented forms: role, company, jobShifts and breaks, or role, company, startTime and endTime. The managed request schema reconciles the provider’s contradictory required-field list against its prose and examples; all 25 official JSON request examples are tested.

The off-cycle payroll creation endpoint is callable but its input is opaque native JSON, not a verified typed field model: Rippling publishes a response-shaped request schema. Its Internal_Testing entitlement remains required. A failed or partial result can still contain created runs; retain the result and reconcile before issuing another request. This endpoint has no documented idempotency header, so Alter never invents one or retries it automatically.

Approvals and maintenance

Approvals show the selected managed operation and contract version, then execute the frozen native request after current authorization checks. Operator audit records retain that same provenance. Existing raw requests remain available.

Source refresh downloads every published namespace into a review candidate and preserves original evidence. Status, error, security and schema changes all trigger review; scheduled checks never overwrite a published contract. Old contracts remain available for installed SDKs and pending approvals. Validation uses official examples and controlled signed transport fixtures; it does not claim live partner-entitled access to every Rippling product.

Compatibility and sensitive data

Custom-setting create/update accepts value alongside the typed value fields, matching the Developer API guide. The same body keys are available for OAuth and managed-secret grants.

Execution-log scope compatibility: For GET /functions/{function}/executions/{execution}/logs, Alter accepts either function-executions.read or the historical functions.read scope, including their documented broader scopes. Existing grants keep their log access without renewal. This compatibility applies only to that log endpoint; neither scope implies the other for function definitions, execution listings, or writes. New connections should declare function-executions.read, matching Rippling’s current permissions table. Rippling still enforces the permissions on the underlying token.

Existing connections retain access to bill-payment, card-transaction, reimbursement, spend-category and spend-vendor reads, and workflow execution creation/reads. These 12 exact operations were previously unclassified. Narrowed grants and delegations with a nonempty scope ceiling retain the prior fallback when their own chain has a method/path restriction; that restriction still gates the requested route. Empty ceilings always remain denied. Unpinned narrowed requests are denied unless their declared scopes satisfy the operation. No adjacent operation or global scope implication is added.

Both typed calls and raw catalogued requests use the same sensitive-input guard. Sensitive input is withheld from approval cards, including already pending requests, and new sensitive requests are refused before durable freezing.

Managed Rippling bodies are excluded from payload capture because payroll/worker responses and errors may carry bank or tax identities; metadata audit remains. Bank account, routing, IBAN, SSN, EIN, date of birth and secret fields cannot be retained in frozen approvals. For custom settings, secret_value is always excluded. Generic value can be retained only when data_type explicitly selects string, number or boolean; an omitted or unknown type might refer to an existing secret and is refused. Use provider-held references or immediately authorized operations for those fields.

HTTP errors follow Rippling’s error contract. For HTTP 2xx, operation-specific predicates detect failed or rejected hires (an incomplete hire was created and is an ordinary result), payroll item failures, unsuccessful deduction updates, and failed metadata validation or deployment outcomes. Historical failures inside activity-log read results are ordinary data, not failures of the read. QuickBooks Fault is not a Rippling envelope.

Resume after a restart

Persist call.approvalId (TypeScript) or call.approval_id (Python), then construct a fresh provider client and call resume(savedId), followed by wait(). The stored approval selects the operation; this installed package verifies its provider and contract version before attaching the response validator. Mismatches raise ManagedOperationError, never silently decode using another contract. See persist-and-resume examples.

Rules for SDK functions

Policy operation fields also accept the published SDK function IDs listed by alter integrations operations <provider>. Use when.operation for a json_match or conditional require_approval rule, or match.operations for content_match (including redaction and step-up). Conditional approval can also use when.match.operations with parameter conditions. alter policy simulate --operation <function-id> tests that exact function.

Managed calls carry a server-verified function identity. Alter still evaluates policy against the actual method, URL and body after building the request from the authorized connection. Existing endpoint, method, host, catalog-operation and family rules continue to apply unchanged.

A raw call can share an endpoint with several SDK functions. It matches all of those function IDs: a deny or approval rule naming any one of them applies. A function name never grants permission or bypasses existing restrictions; Alter’s policy rules only narrow access and do not accept an allow effect. The portal’s operation picker lists searchable SDK names grouped by product, alongside the existing catalog operations. alter providers operations list shows the functions covered by each catalog operation.

For example, this rule requires approval for rippling.base_api.cancel_leave_requests:

{
  "effect": "require_approval",
  "when": { "operation": "rippling.base_api.cancel_leave_requests" },
  "approval": { "approvers": ["reviewer@example.com"] }
}

Save it with alter policy rules create --app <app-id> --grant <grant-id> --type require_approval --body @rule.json, or select the function in the portal.