Ramp SDK: get started

Use an ordinary App, or an Agent when the workload needs agent identity. Alter builds provider requests from a reviewed contract and applies the same connection authorization, policy, approvals, and audit records as raw requests.

Install

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

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

Connect and call

Configure Ramp, request the scopes the application needs, and retain each customer’s grant ID after Connect consent. Alter supplies the credential; it never belongs in operation input.

import { App } from "@alter-ai/sdk";
import { RampIntegration } from "@alter-ai/ramp";
const app = new App({ apiKey: process.env.ALTER_API_KEY! });
try {
  const client = new RampIntegration(app, { grantId: process.env.RAMP_GRANT_ID! });
  const result = await (await client.user.getUserListWithPagination({})).wait();
  console.log(result.bodyJson());
} finally {
  await app.close();
}

from alter_sdk import App
from alter_sdk_ramp import RampIntegration

async def first_call(api_key: str, grant_id: str):
    async with App(api_key=api_key) as app:
        client = RampIntegration(app, {"grant_id": grant_id})
        call = await client.user.get_user_list_with_pagination({})
        result = await call.wait()
        return result.body_json()

Complete versioned contract

Contract 2026-10-27 contains every operation in Ramp’s official OpenAPI document. It ships in provider SDK 0.2.1 and adds the Payments API (list, fetch, create, update, retry and cancel payments, remittance receipts and the check preview), billing statements and vendor payment methods; the previous 2026-10-26 contract remains available for existing clients and pending approvals. The API reference links every operation to its complete input fields, response models, TypeScript and Python examples, and policy identity. Browse by resource under this provider’s API reference in the Integrations sidebar, or download the pinned OpenAPI specification. The Developer Portal provider view and alter integrations operations ramp --version 2026-10-27 also expose the schemas.

Generated calls pin the Alter contract version. Ramp’s own product, role, scope and subscription requirements still apply. There is no silent version fallback and no automatic write retry or pagination.

alter integrations execute ramp ramp.get_user_list_with_pagination \
  --version 2026-10-27 --grant "$RAMP_GRANT_ID" --input '{}' --wait

Arguments use native path, query, headers, and body containers. Array query parameters are sent the way Ramp’s document declares them: comma-separated where it declares a delimited list (the status, provider and id filters), repeated keys otherwise. SDK methods preserve provider field names, decimal lexemes and large integers as strings when necessary. HTTP 204 returns null / None from the typed decoder. Binary responses use bodyBytes() / body_bytes(); the CLI can save them with --output-file.

Approvals

A policy rule can require approval for any operation. The call returns a pending approval; wait() resolves once the approver decides, and resume(approvalId) picks a pending approval up after a restart. Approval cards show the operation, its contract version and the request input the sensitivity review marked safe to display.

Uploads and approvals

Every binary input is a JSON object with filename, content_type, and content_base64; documents on a vendor agreement accepts an array of those objects. Ramp’s eight uploads (bill and draft-bill attachments, receipts, reimbursement receipts, request attachments, agreement documents, OCR drafts and blank-canvas documents) are plain named multipart parts: each body field is a part, a file object is a file part, and an optional field left null is omitted. The shared proxy accepts up to 5 MiB of serialized input and encoded upload data; base64 adds overhead, so accepted file bytes are smaller than that ceiling.

Every uploaded document is classified sensitive, so an upload cannot be frozen for a require_approval rule: it executes immediately when authorized or is refused with sensitive_input_not_retained. Approval pages for other operations show the exact semantic fields; frozen execution uses the stored input and the original contract, rechecks current authority, and never replays an uncertain write.

Ramp’s documentation describes the document part of three uploads with Content-Disposition: attachment; Alter sends the standard form-data disposition with a file name. No Ramp sandbox credentials exist in Alter yet, so this wire shape is verified against the schema and the hermetic transport, not against Ramp.

Policy and sensitive data

Every write has a reviewed method/path family entry in the provider input; an unreviewed new write fails generation. Payments (create, update, retry and cancel), bills and their holds and releases, mileage reimbursements, vendor bank-account changes and payment holds, and the issuance of spend authority (funds, spend programs, un-suspending a fund or member, embedded-card tokens) include payment (cancelling a payment is also delete and write, and the check preview, which only computes how an address and memo print, is read); user invites, financing applications and comments include send; user, department, location, webhook, accounting-connection and AI-spend settings changes include admin. The 30 operations Alter cataloged before this publication keep exactly their earlier families, so existing rules keep their meaning.

Managed Ramp body capture is disabled because responses and errors carry payee bank details, card data and personal identifiers; metadata audit remains. Bank account and routing numbers, crypto wallet addresses, the last four digits of SSNs and passports, EINs and tax ids, dates of birth, the PKCE code challenge and every uploaded document cannot be retained in frozen approvals. Provider-held references, enums, names, flags and immediately authorized execution remain available.

Four operations Ramp documents are not published: the card-vault operations (GET/POST /developer/v1/cards/vault, /vault/cards) require cards:read_vault, which the Ramp connection deliberately does not offer. Ramp’s token and revocation endpoints are not operations either; a raw request to them is refused by policy as credential minting, and so is a raw POST whose path cannot be read well enough to rule those endpoints out (unusual encoding, a backslash, or a path past the length limits).

Fault detection follows Ramp’s successful-response schemas: a webhook verification that answers {"success": false} is a fault, so ok is false and bodyJson() / body_json() raises. Ordinary errors use HTTP error statuses.

Maintenance

The pinned official source, its hash, the generated methods and the policy mapping are checked together. Scheduled checks save upstream candidates and report additions, removals and schema changes; they never replace a published contract automatically. Existing contract versions remain available for installed SDKs and pending approvals.

Sandbox connections use Ramp’s demo deployment (demo.ramp.com, demo-api.ramp.com) with a separate sandbox developer app; select the sandbox environment when configuring sandbox credentials.

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 ramp. 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 and matches all of them; a function name never grants permission or bypasses existing restrictions.

For example, this rule requires approval before a vendor’s payout destination changes:

{
  "effect": "require_approval",
  "when": { "operation": "ramp.post_vendor_bank_account_update_resource" },
  "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.