A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Ramp API is how an app or AI agent works with a Ramp account: listing card transactions, issuing a virtual card, setting a spend limit, or reading reimbursements and bills. Access is granted through an OAuth 2.0 access token, and each method requires a scope named like transactions:read or cards:write that sets which resources a call can read or write. Ramp serves a single version of the API and can push events, like a transaction clearing or a bill being paid, to a subscribed endpoint.
How an app or AI agent connects to Ramp determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Ramp tools to agents, and each is governed by the access token behind it and the scopes that token carries.
The REST API returns JSON and pages through lists with a cursor, at https://api.ramp.com/developer/v1. A call authenticates with an OAuth 2.0 Bearer access token, and each method requires a specific scope like transactions:read or cards:write. A request that runs longer than 60 seconds is cut off with a 504.
Ramp publishes a first-party, open-source Model Context Protocol server, ramp_mcp, that exposes Ramp Developer API data and tasks to AI agents and LLM clients. It loads data into an in-memory SQLite database so an agent can query and analyze spend in natural language. It authenticates with an OAuth client-credentials token and is governed by the scopes granted to that token.
Ramp POSTs event payloads to an HTTPS endpoint registered through the webhooks API. The receiver verifies the X-Ramp-Signature header, an HMAC-SHA256 of the raw request body signed with the subscription's secret, to confirm the request came from Ramp. Subscriptions are scoped to event types like transactions.cleared and bills.paid.
The client-credentials flow exchanges a client id and secret for an access token at https://api.ramp.com/developer/v1/token, with no user present. The token represents the application itself and carries the scopes granted to the client. It is the route for server-to-server integrations and for the MCP server.
The authorization-code flow sends a user to https://api.ramp.com/v1/authorize to consent, then exchanges the returned code for an access token at the token endpoint. The token represents that user and the scopes they approved, and a refresh token lets the app obtain new access tokens without re-prompting.
The Ramp API is split into areas an agent can act on, like transactions, cards, users, spend limits, reimbursements, and bills. Each area has its own methods and its own scopes, and writes in some areas issue cards, move money, or change who can spend.
Methods for reading and annotating card transactions.
Methods for listing, issuing, and controlling cards.
Methods for listing, inviting, and managing users.
Methods for creating and adjusting spend limits.
Methods for working with spend programs.
Methods for reading and creating reimbursements.
Methods for creating, reading, and paying bills.
Methods for reading and uploading receipts.
Methods for the org structure used to scope spend.
Methods for reading merchant reference data.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
TransactionsMethods for reading and annotating card transactions.3 | ||||||
| GET | /developer/v1/transactions | List card transactions, filterable by date, amount, card, user, merchant, and state. | read | transactions:read | Current | |
Read-only. Acts ontransaction Permission (capability) transactions:readVersionAvailable since the API’s base version Webhook event transactions.clearedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/transactions/{transaction_id} | Fetch a single transaction by id. | read | transactions:read | Current | |
Read-only. Acts ontransaction Permission (capability) transactions:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /developer/v1/transactions/{transaction_id} | Update a transaction, for example to set accounting fields or a memo. | write | transactions:write | Current | |
Changes accounting and memo data on a real transaction. Acts ontransaction Permission (capability) transactions:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CardsMethods for listing, issuing, and controlling cards.6 | ||||||
| GET | /developer/v1/cards | List cards in the business. | read | cards:read | Current | |
Read-only; returns card metadata, not full numbers. Acts oncard Permission (capability) cards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/cards/{card_id} | Fetch a single card by id. | read | cards:read | Current | |
Read-only metadata; sensitive numbers need cards:read_vault. Acts oncard Permission (capability) cards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/cards/deferred/virtual | Create a virtual card. The call returns a task id and the card is created asynchronously. | write | cards:write | Current | |
Issues a real spending card; resolve the task to get the card. Acts oncard Permission (capability) cards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /developer/v1/cards/{card_id} | Update a card, for example its display name or spending controls. | write | cards:write | Current | |
Changes controls on a live card. Acts oncard Permission (capability) cards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/cards/{card_id}/deferred/termination | Terminate a card permanently. Processed asynchronously and returns a task id. | write | cards:write | Current | |
Irreversible; the card can no longer be used. Acts oncard Permission (capability) cards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/vault/cards/{card_id} | Fetch a card's sensitive details, like the full number, from the vault. | read | cards:read_vault | Current | |
Returns full card numbers; a separate, narrower scope than cards:read. Acts oncard Permission (capability) cards:read_vaultVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersMethods for listing, inviting, and managing users.4 | ||||||
| GET | /developer/v1/users | List users in the business. | read | users:read | Current | |
Read-only; returns names, emails, roles, and department. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/users/{user_id} | Fetch a single user by id. | read | users:read | Current | |
Read-only. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/users/deferred | Invite a new user. Processed asynchronously and returns a task id. | write | users:write | Current | |
Adds a person to the business with a role. Acts onuser Permission (capability) users:writeVersionAvailable since the API’s base version Webhook event users.invite_acceptedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /developer/v1/users/{user_id}/deactivate | Deactivate a user so they can no longer access the business. | write | users:write | Current | |
Revokes a person's access. Acts onuser Permission (capability) users:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Spend limitsMethods for creating and adjusting spend limits.3 | ||||||
| GET | /developer/v1/limits | List spend limits. | read | limits:read | Current | |
Read-only. Acts onspend_limit Permission (capability) limits:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/limits/deferred | Create a spend limit. Processed asynchronously and returns a task id. | write | limits:write | Current | |
Sets how much can be spent and by whom. Acts onspend_limit Permission (capability) limits:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /developer/v1/limits/{spend_limit_id} | Update a spend limit. | write | limits:write | Current | |
Changes a live spending allowance. Acts onspend_limit Permission (capability) limits:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Spend programsMethods for working with spend programs.2 | ||||||
| GET | /developer/v1/spend-programs | List spend programs, the reusable templates that govern spending. | read | spend_programs:read | Current | |
Read-only. Acts onspend_program Permission (capability) spend_programs:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/spend-programs | Create a spend program. | write | spend_programs:write | Current | |
Defines a reusable spending policy. Acts onspend_program Permission (capability) spend_programs:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReimbursementsMethods for reading and creating reimbursements.3 | ||||||
| GET | /developer/v1/reimbursements | List reimbursements. | read | reimbursements:read | Current | |
Read-only. Acts onreimbursement Permission (capability) reimbursements:readVersionAvailable since the API’s base version Webhook event reimbursements.ready_for_reviewRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/reimbursements/{reimbursement_id} | Fetch a single reimbursement by id. | read | reimbursements:read | Current | |
Read-only. Acts onreimbursement Permission (capability) reimbursements:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/reimbursements/mileage | Create a mileage reimbursement. | write | reimbursements:write | Current | |
Creates a real reimbursement claim. Acts onreimbursement Permission (capability) reimbursements:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
BillsMethods for creating, reading, and paying bills.3 | ||||||
| GET | /developer/v1/bills | List bills. | read | bills:read | Current | |
Read-only. Acts onbill Permission (capability) bills:readVersionAvailable since the API’s base version Webhook event bills.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/bills | Create a bill. | write | bills:write | Current | |
Creates a real bill payable to a vendor. Acts onbill Permission (capability) bills:writeVersionAvailable since the API’s base version Webhook event bills.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/bills/{bill_id} | Fetch a single bill by id. | read | bills:read | Current | |
Read-only. Acts onbill Permission (capability) bills:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ReceiptsMethods for reading and uploading receipts.2 | ||||||
| GET | /developer/v1/receipts | List receipts. | read | receipts:read | Current | |
Read-only. Acts onreceipt Permission (capability) receipts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/receipts | Upload a receipt. | write | receipts:write | Current | |
Adds a receipt to the account. Acts onreceipt Permission (capability) receipts:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Departments & locationsMethods for the org structure used to scope spend.3 | ||||||
| GET | /developer/v1/departments | List departments. | read | departments:read | Current | |
Read-only. Acts ondepartment Permission (capability) departments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /developer/v1/departments | Create a department. | write | departments:write | Current | |
Changes the org structure. Acts ondepartment Permission (capability) departments:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /developer/v1/locations | List locations. | read | locations:read | Current | |
Read-only. Acts onlocation Permission (capability) locations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
MerchantsMethods for reading merchant reference data.1 | ||||||
| GET | /developer/v1/merchants | List merchants, the reference data behind transactions. | read | merchants:read | Current | |
Read-only reference data. Acts onmerchant Permission (capability) merchants:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Ramp can notify an app when something happens in an account, like a transaction clearing or a bill being paid. It posts an event to a subscribed endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
transactions.cleared | A card transaction cleared and settled. | /developer/v1/transactions |
transactions.authorized | A card transaction was authorized, before it clears. | In-app only |
transactions.declined | A card transaction was declined. | In-app only |
bills.created | A bill was created. | /developer/v1/bills/developer/v1/bills |
bills.paid | A bill was paid. | In-app only |
reimbursements.ready_for_review | A reimbursement is ready for review. | /developer/v1/reimbursements |
users.invite_accepted | An invited user accepted the invite and joined the business. | /developer/v1/users/deferred |
Ramp limits how fast an app can call, by a request count measured over a short rolling window, and cuts off any single request that runs too long.
Ramp meters requests by a count over a short rolling window rather than by a per-method cost. The documented limit is 200 requests per 10-second rolling window per source IP address, roughly 1,200 per minute. Going over returns HTTP 429. Separately, any single request that runs longer than 60 seconds is terminated with a 504, so large reads should be narrowed and paged.
A list endpoint is cursor-based. The page_size parameter sets how many results come back, between 2 and 100 with a default of 20, and the start parameter takes the id of the last item from the previous page to fetch the next one. The response carries a next-page reference so an integration can walk through all results.
A list page returns at most 100 items, the maximum value of page_size. Reads are bounded by the 60-second request timeout rather than a fixed result cap, so very large pulls are paged.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | The request was malformed or a parameter was missing or invalid. | Read the error body, fix the parameters, and resend. The request is not retryable as-is. |
| 401 | unauthorized | The access token is missing, expired, or invalid. | Obtain a fresh token through the OAuth flow, and confirm it is sent as a Bearer token. |
| 403 | forbidden | The token is valid but lacks the scope the request needs, like a transactions:read token calling a write method. | Grant the missing scope to the client and re-issue the token. |
| 404 | not_found | The requested object does not exist or is not visible to this token. | Verify the object id and that it belongs to the authenticated business. |
| 422 | unprocessable_entity | The request was well-formed but failed a validation rule on the data. | Correct the values flagged in the response and resend. |
| 429 | too_many_requests | The rate limit was exceeded for the calling source. | Back off and retry with exponential backoff, and smooth the request rate under the rolling-window limit. |
| 504 | gateway_timeout | The request took longer than 60 seconds and was terminated. | Narrow filters or page sizes so the request completes within the limit, then retry. |
Ramp serves one version of its developer API, identified as v1, and ships dated changes to it through a public changelog rather than minting a new version string.
Ramp serves a single version of its developer API, identified as v1 in the path, with no dated version string to pin. Changes ship to v1 in place and are published in a public, dated changelog, so an integration tracks the changelog rather than migrating between versions.
The v1 API received frequent dated updates through the first half of 2026, published in the changelog. Each ships additively to the single v1 surface rather than minting a new version.
A documented batch of additive changes across several resources, shipped to v1.
Track the changelog, since changes ship to the single v1 API in place.
Ramp API changelog ↗Bollard AI sits between a team's AI agents and Ramp. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.