# Ramp Developer API Guides Plain-text guide export for Ramp's Developer API. title: Accounting source_url: /developer-api/v1/accounting text_url: /llms-guides/accounting.txt summary: Ramp's API can be used to keep data in sync between Ramp and an external accounting system. content: Ramp's API can be used to keep data in sync between Ramp and an external accounting system. This guide is targeted towards developers building a connection between Ramp and a remote accounting/ERP system. By following this guide, you'll enable seamless data flow between Ramp and your ERP, keeping vendors, GL accounts, and transaction data synchronized. Building an accounting integration involves three main steps: configuring the connection, uploading your chart of accounts, and implementing object sync. Before you start 1. Configure Accounting Connection 2. Upload COA and Custom Fields 3. Implement Object Sync 4. Advanced Configuration (Optional) There are three core processes that must be built as part of an accounting integration: Configure Connection Establish an accounting connection between Ramp and your ERP system. Chart of Accounts Import GL accounts, custom fields, field options, and vendors from your ERP into Ramp. Object Sync Fetch ready-to-sync objects from Ramp, transfer them to your ERP, and mark them as synced. Create Accounting Connection Before syncing your chart of accounts, you need to establish an accounting connection between Ramp and your ERP system. This connection serves as the foundation for all accounting data synchronization. You can check if an accounting connection already exists by calling the GET /developer/v1/accounting/connection endpoint: If you need to disconnect an existing accounting connection, use the DELETE /developer/v1/accounting/connection endpoint: Disconnecting will clear accounting data Disconnecting an accounting connection will remove all associated custom fields, GL accounts, and vendors. See the Migration section for guidance on preserving data during connection changes. To create a new Developer API accounting connection, use the POST /developer/v1/accounting/connection endpoint: The remote_provider_name field identifies your accounting system. Chart of Accounts and Custom Fields When integrating your ERP with Ramp, one of the first setup steps is syncing your chart of accounts — the list of general ledger accounts, vendors, and classification fields that ensure every Ramp transaction is properly coded in your ERP. This section walks through how to: Understand what's imported into Ramp from your ERP Upload data for each category (GL Accounts, Custom Fields, Vendors) Verify the data inside the Ramp UI after import GL Accounts ✅ Always required API configurable Primary accounting categories (e.g., expense or revenue accounts). POST /developer/v1/accounting/accounts Custom Fields ⚙️ Optional Adds metadata such as department or cost center. POST /developer/v1/accounting/fields Custom Field Options Options for custom fields (e.g., department values). POST /developer/v1/accounting/field-options Vendors Defines supplier names for bills or transactions. POST /developer/v1/accounting/vendors Entities UI only (read-only via API) Business units or subsidiaries configured directly in Ramp. UI only Chart of Accounts cannot be modified for Ramp accounts using a direct accounting connection This applies to GL accounts, custom fields, and vendors - they become read-only via API when a direct connection is active. GL Accounts define the categories under which your company records transactions — such as expenses, revenue, or assets. These accounts are imported from your ERP and uploaded to Ramp to ensure consistent coding across systems. Example GL accounts: EXPENSE 6410 514 Employees: Salaries & Wages — 418 Office/Admin: Phone & Internet REVENUE 425 Sales To upload your GL accounts to Ramp, use the POST /developer/v1/accounting/accounts endpoint: Once you make the POST call, this is what the GL accounts look like in the Ramp UI: Custom fields let you import classifications from your ERP like Department, Cost Center, or Location. Example Custom Field: Department SINGLE_CHOICE To create a new custom field in Ramp, use the POST /developer/v1/accounting/fields endpoint: Once you make the POST call, this is what the custom field looks like in the Ramp UI: The POST call to create an accounting field will return a ramp_id in the response if successful. To upload custom field options to Ramp, use the POST /developer/v1/accounting/field-options endpoint using the ramp_id from the API call: Example Custom Field Options: Engineering & Design Sales & Marketing Once you make the POST calls, this is what the field looks like in the Ramp UI: Vendors represent suppliers or payees from your ERP and allow users to tag bills, transactions, or purchase orders in Ramp. Example Vendor Data: V-5500-0130 AirTable V-5500-0135 Slack Technologies, LLC V-5500-0142 Microsoft To upload your vendors to Ramp, use the POST /developer/v1/accounting/vendors endpoint: Once you make the POST call, this is what the field looks like in the Ramp UI: When managing your chart of accounts in Ramp, there are two distinct ways to remove an item (field option, GL account, or vendor) from cardholder selection: deleting (deactivating) and hiding. Choosing the right approach depends on whether you want to preserve the ability to sync data for that item in the future. Use the DELETE endpoint when you never want to sync the item again. This marks the item as inactive (is_active: false), which: Removes it from cardholder selection in the Ramp UI Prevents it from being used in future transaction coding Does not permanently remove the record — it can be reactivated later if needed Deleting is appropriate for items that have been retired from your ERP and should no longer appear anywhere in Ramp. Custom field options DELETE /developer/v1/accounting/field-options/{field_option_id} Custom fields DELETE /developer/v1/accounting/fields/{field_id} GL accounts DELETE /developer/v1/accounting/accounts/{gl_account_id} DELETE /developer/v1/accounting/vendors/{vendor_id} Example — delete a vendor: To reactivate any deleted item, send a PATCH request with "reactivate": true: Use the visibility field on a custom field option when you want to stop cardholders from coding new transactions with it, but preserve values that have already been coded. Setting visibility to HIDDEN: Removes the option from cardholder selection dropdowns Keeps the option active (is_active: true) so existing codings are preserved and can still be synced Allows you to make it selectable again at any time by setting visibility back to VISIBLE Hiding is appropriate when a field option is no longer in active use in your ERP but you still need to sync historical transactions that reference it. Example — hide a field option: Example — make a hidden field option visible again: Use when You never want to sync this item again You want to stop new coding but preserve historical values Effect on is_active Sets to false Remains true Visible to cardholders No Existing codings preserved Yes, but item cannot be synced Yes, and item can still be synced How to reverse PATCH with "reactivate": true PATCH with "visibility": "VISIBLE" Applies to Fields, field options, GL accounts, vendors Field options only Choosing the right approach If in doubt, prefer hiding over deleting for field options. Hiding is less disruptive because it keeps the option active for sync purposes. Only use DELETE when you are certain the item should be fully deactivated. Accounting vendors (ERP-side identifiers) and Ramp vendors are separate entities that can be linked together. Here's how to set up and connect them: 1. Create or update Accounting vendors Use the POST /developer/v1/accounting/vendors endpoint to create accounting vendors with your ERP-side identifiers: 2. Link the Ramp vendor to the Accounting vendor Update the existing Ramp vendor to point to the correct accounting vendor using accounting_vendor_remote_id via PATCH /developer/v1/vendors/{vendor_id}: 3. (Optional) Set a vendor code on the Accounting vendor If your ERP setup expects a separate "code" field (distinct from the remote ID), set it directly on the accounting vendor using PATCH /developer/v1/accounting/vendors/{vendor_id}: For organizations with multiple business entities (subsidiaries, divisions, etc.), entities are created and managed directly in the Ramp UI. When fetching objects via the API, you can scope requests to a specific entity using the entity_id parameter. See Managing multiple entities for more information on setting up entities in Ramp. When uploading chart of accounts data, several endpoints support batch operations with specific limits. All batch operations use "all-or-nothing" processing - if any item in a batch fails validation, the entire batch is rejected: General Ledger Accounts 500 accounts Accounting Vendors 500 vendors 500 options Accounting Syncs 5,000 records Multiple API Calls Supported These limits apply per API call, not as total limits. You can make multiple API calls to upload more than the per-call limit. For example, to upload 2,000 custom field options, you would make 4 separate API calls with 500 options each. To sync accounting data between Ramp and your ERP system, you'll need to implement an object sync process. This process involves: Fetching ready-to-sync objects from Ramp using the API Transferring the data to your ERP system Marking objects as synced in Ramp once successfully transferred using the Sync Status endpoint Once an object has been marked as synced, it will no longer be visible in the primary Accounting View of the account. Objects cannot be marked as synced via API when using a direct accounting connection Objects in Ramp follow different patterns for when they become ready to sync with your ERP system. Some objects are automatically marked as ready based on their status, while others require manual action by users in the Ramp UI. Bills Automatic Ready when not deleted AND either approved or created (based on accounting settings) AND not yet synced Bill Payments Ready when not deleted AND fully paid (payment_status=PAID) Transfers Ready when transfer payment is accepted Cashback Payments Automatically ready to sync without user action Transactions Manual Users must mark as 'ready to sync' in Ramp UI Reimbursements For transactions and reimbursements that require manual action, users can mark them as ready to sync in the Ramp UI: 1. ERP makes API call to Ramp to fetch ready-to-sync transactions To fetch ready-to-sync transactions, make an API call to GET /developer/v1/transactions?sync_status=SYNC_READY. 2. Ramp responds with list of transactions that are ready to sync Here's an example response Ramp sends in response to GET /developer/v1/transactions?sync_status=SYNC_READY (additional fields are available not shown here): 3. ERP processes the data and uploads it to the remote accounting system Process the transaction data and create the corresponding entries in your ERP system using the accounting categories, line items, and other relevant fields. 4. ERP calls Ramp's sync endpoint to mark objects as synced Call POST /developer/v1/accounting/syncs to notify Ramp of a list of sync results. An idempotency key is required to ensure that subsequent requests are properly handled. Bills require a two-step sync process: first sync the invoice, then sync the payment once it's complete. Invoice Sync Fetch bills that haven't been synced yet: After you create the invoice in your ERP, mark the bill as invoice-synced in Ramp: This updates the bill's sync_status to BILL_SYNCED. Payment Sync Once the bill is paid, fetch bills that have been invoice-synced but not payment-synced: After you create the payment in your ERP, mark the payment as synced in Ramp: There are two methods for implementing object sync between Ramp and your remote system: Polling: Periodically fetch ready-to-sync objects from Ramp API endpoints Webhooks: Receive real-time notifications when objects become ready to sync Polling The polling method involves periodically fetching ready-to-sync objects from Ramp API endpoints. We recommend polling every 1–4 hours on weekdays and every 12 hours on weekends for the latest information. The polling object sync process follows this flow: ERP makes API calls to Ramp to fetch objects that are ready to sync Ramp responds with a list of objects that are ready to sync ERP processes the data and uploads it to the remote accounting system ERP calls Ramp's sync endpoint to mark objects as synced Use these endpoints to fetch objects that are ready to sync from Ramp: GET /developer/v1/bills?sync_ready=true GET /developer/v1/transactions?sync_status=SYNC_READY GET /developer/v1/reimbursements?sync_status=SYNC_READY GET /developer/v1/transfers?sync_status=SYNC_READY Cashbacks GET /developer/v1/cashbacks?sync_status=SYNC_READY Webhooks Instead of polling for ready-to-sync objects, you can use webhooks to receive real-time notifications when objects become ready to sync. This eliminates the need for frequent polling and provides immediate notifications. Supported Webhook Events You can subscribe to these webhook events for real-time sync notifications: transactions.ready_to_sync: Triggered when transactions are marked as ready to sync Setting Up Webhooks To implement webhook-based object sync: Configure webhook endpoints in your ERP system to receive notifications Subscribe to relevant events using Ramp's webhook configuration Process incoming webhook payloads to identify ready-to-sync objects Fetch object details using the appropriate API endpoints Mark objects as synced after successful transfer For detailed webhook setup instructions, see our Webhooks Guide. Manual Exports Objects ready to sync can optionally be Exported from the accounting tab, which will automatically mark them as synced. It's important to inform customers using an API-based ERP connection to not use this export button. In cases when you are unable to sync an object to the remote system, you can use the failed_syncs parameter on the Sync Status endpoint to convey issues back to the user. These issues will be displayed in the Accounting tab as Export Errors. Errors generally fall into three categories: User-actionable Error title + resolution steps "Accounting period is closed. Open the period in NetSuite and retry." Transient / retryable Error title + prompt to retry "NetSuite is temporarily unavailable. Please try again in a few minutes." Requires integrator support Error title + support contact with reference ID "Unexpected error syncing transaction. Reach out to us at support@example.com with reference ID abc123 for more help." Automatically migrate your existing accounting connection with our ERP Migration Tool (in Beta). Sync Outstanding Data: Ensure all ready-to-sync objects (transactions, bills, reimbursements) are marked as synced via the API or Ramp UI. This avoids losing data during migration. Document Rules and Automations: Export or note all accounting rules, automations, and configurations. These will need to be recreated with the new connection. Fetch and Store the Current Chart of Accounts: Use the Accounting Custom Fields API to fetch current custom fields. Use the Accounting GL Accounts API to fetch all active GL accounts. Use the Accounting Vendors API to fetch vendor data. Use the Accounting Custom Fields API to fetch current custom fields. Use the Accounting GL Accounts API to fetch all active GL accounts. Use the Accounting Vendors API to fetch vendor data. Save the fetched data securely for re-upload after creating the new connection. Disconnect the Existing Connection: Use the Accounting Connection API to disable the current connection. This action will clear associated accounting settings (Custom Fields, GL Accounts, Vendors). Create the New Connection: Establish the new connection via the API or Ramp UI. Reconfigure and Re-upload Data: Use the Accounting Custom Fields API to upload custom fields. Use the Accounting GL Accounts API to upload GL accounts. Use the Accounting Vendors API to upload vendor data. Use the Accounting Custom Fields API to upload custom fields. Use the Accounting GL Accounts API to upload GL accounts. Use the Accounting Vendors API to upload vendor data. Verify and Test the New Connection: Perform a small batch test to ensure the new connection is working as expected. Validate that synced data appears correctly in the new accounting system. Follow the instructions in this article to rebuild any accounting automations within the Ramp account. Migrating Accounting Connections will result in a loss of historical chart of accounts codings. Ensure chart of accounts is backed up before proceeding with a migration. Accounting Connection Understand and manage the current state of an account's Accounting Connection. Accounting Custom Fields Leverage fields to code transactions, reimbursements, and bills. Manage Vendor options for coding transactions, reimbursements, bills, and purchase orders. Accounting Sync Mark objects as 'synced' after successful addition to the remote accounting system. Accounting GL Accounts Manage GL accounts used for coding transactions, reimbursements, bills, and purchase orders. View business entities associated with a Ramp account. Fetch accounting codings and metadata from card transactions. Fetch accounting codings and metadata from bills and payments. Fetch accounting codings and metadata from employee reimbursements. Fetch accounting codings and metadata from cashback earned via Ramp cards. Statements Fetch payments for Ramp card statements. Purchase Orders Fetch and create purchase orders. Are Purchase Orders available with all connection types? Yes, purchase orders can be fetched and created via the API regardless of your accounting connection type. POs are not considered part of the accounting connection configuration—they're a separate feature available to all users with API access. Is it possible to have multiple Accounting Connections active at once as part of a customer migration? No, this is a known limitation of migrating Ramp accounts between connections. Are there any limitations to the lookback period for API objects such as Transactions? There are no lookback limits; all historical objects are available via API. Can I fetch payments associated with a bill via the API? Yes, payment details are nested within the Bill object. Use the Bills API to fetch the payment_status field and update the sync status accordingly once the payment is completed. Do users need to configure both Ramp and their finance/ERP systems for integrations to work? Yes, most integrations require setup on both ends: Ramp: Users authorize the app with the necessary permissions for the integration use case. Remote System: Users often need to configure endpoints, set up API access, or install connectors to accept data from Ramp. Does Ramp enforce encryption for data transmissions? Yes, Ramp ensures encryption across all data transmissions: HTTPS Encryption: All API requests and responses are encrypted using HTTPS. Data Storage: Data stored in Ramp systems is encrypted for security. For additional encryption needs, developers can implement payload-level encryption before sending or receiving data, as required. Can apps be hosted on Ramp infrastructure? Currently, apps must be hosted externally, meaning they run on partner infrastructure and integrate with Ramp via APIs. While hosting on Ramp's infrastructure is not currently supported, it could be considered in the future for specific apps requiring deeper integration or enhanced control. --- title: ERP Migration Tool source_url: /developer-api/v1/accounting-erp-migration text_url: /llms-guides/accounting-erp-migration.txt summary: This guide explains how integrators can set up a new API-based accounting connection to use the ERP migration tool. content: This guide explains how integrators can set up a new API-based accounting connection to use the ERP migration tool. Feature Access Required Note: This feature is currently in Beta and must be manually enabled by Ramp. Please reach out to your Account Manager for assistance. Requirements Your app must have scopes accounting:read and accounting:write Make a POST to create a new, inactive accounting connection Choose a descriptive customer-facing name for remote_provider_name and set is_active to false: Example response Notes Status should be unlinked remote_provider_name appears in the customer UI when they switch providers Save the returned id for subsequent calls For write operations to set up the custom fields and chart of accounts, include the id from the previous request for the accounting_connection_id in the request body: 2a. Upload GL accounts 2b. Create a custom accounting field 2c. Add options for a custom field 2d. Upload vendors After setting up the COA and custom fields Call POST developer/v1/accounting/connection//ready-to-migrate to mark the inactive connection as ready. This makes the new provider selectable in the customer UI Result The inactive accounting connection is marked as ready The customer can now switch to this provider in the UI Navigate to Accounting → Settings → Danger Zone → Switch Providers: Select the inactive provider by the title you chose for remote_provider_name: Follow the on-screen steps to map fields from the old connection to the new one and complete migration --- title: Applications source_url: /developer-api/v1/applications text_url: /llms-guides/applications.txt summary: The Applications API lets developers programmatically pre-fill Ramp applications on behalf of new businesses. Each application creates a new business in Ramp and kicks off an asynchronous approval process. content: The Applications API lets developers programmatically pre-fill Ramp applications on behalf of new businesses. Each application creates a new business in Ramp and kicks off an asynchronous approval process. Note that this API creates and pre-fills but does not submit the application - in all cases, the end user will have to submit the application from the Ramp UX. How It Works The application flow has three participants: your platform, Ramp, and the applicant (the business signing up). Submit the application — You call POST /applications with the applicant's information Applicant receives an email — Ramp sends the applicant an email with sign-up instructions Applicant completes sign-up — The applicant creates their Ramp account. At this point, the user may be redirected either to the application or an OAuth consent screen. User completes and submits the application in browser - the user verifies their information is correct, performs final steps and submits application for Ramp review Ramp reviews the application — The application goes through Ramp's approval process Application is approved or rejected — Subscribe to webhooks to get notified of status changes Authorization You must use the Client Credentials grant type to create a new application; the POST endpoint does not require any scopes. To read application status afterward, you'll need the applications:read scope granted on the applicant business via the Authorization Code flow. Submitting an Application Use POST /applications to submit a new application. The POST endpoint is designed to be safely retried: If the applicant's email doesn't exist in Ramp, a new business and application are created If the email already exists and the business is still in the application stage, the invitation email is re-sent If the business is already approved, the request is a no-op The endpoint returns a success response in all cases, with no response body. OAuth Provide oauth_authorize_params in your request to redirect the user to Ramp's OAuth consent screen after accepting their invite. You include oauth_authorize_params with a redirect_uri and state in the POST request After the applicant accepts the invite and signs up, they're shown an OAuth consent screen asking them to grant your app the applications:read and applications:write scopes Upon approval, the applicant is redirected to your redirect_uri with an authorization code and state You exchange the code for an access token, giving you API access to the application for the new business Without oauth_authorize_params, the applicant is sent directly to the Ramp application after accepting the invite — no OAuth consent screen is shown. However, you may still prompt the user to authorize the connection later. redirect_uri requirements The redirect_uri must be registered in your app's configuration in the Ramp Developer Console and must use HTTPS (or localhost for development). After the applicant approves access, exchange the authorization code for a token as described in the Authorization Guide. After the OAuth handoff completes — or at any point after submitting an application — you can link the applicant to Ramp's sign-in page to finish their application: The email query parameter is optional. When provided, it auto-populates the email field on the sign-in page so the applicant doesn't have to type it in. Invite must be accepted first The applicant won't be able to sign in until they've accepted the email invite from Ramp. If they haven't received or accepted the invite yet, direct them to check their inbox first. Application Status Lifecycle Each application moves through the following statuses: STARTED Application has been created but the applicant hasn't completed sign-up yet IN_REVIEW Application has been submitted and is under review by Ramp FOLLOW_UPS_REQUIRED Ramp needs additional information from the applicant APPROVED Application has been approved — the business can start using Ramp REJECTED Application has been rejected WITHDRAWN Application has been withdrawn by the applicant Use GET /applications to check the current status. This endpoint requires the applications:read scope, which means you'll need an access token obtained through the Authorization Code flow. Subscribe to the applications.status_updated webhook event to get notified when an application's status changes. The webhook payload includes the application ID and its new status: When you receive this event, call GET /applications to fetch the full application details and current status. See the Webhooks Guide for setup instructions. Submit a Developer API support ticket and our team will follow up. --- title: Authorization source_url: /developer-api/v1/authorization text_url: /llms-guides/authorization.txt summary: Ramp uses OAuth 2.0 for secure API access, providing granular permission control through scopes and supporting multiple authorization flows for different use cases. content: Ramp uses OAuth 2.0 for secure API access, providing granular permission control through scopes and supporting multiple authorization flows for different use cases. This guide covers the authorization framework in depth. For a quick start making your first API calls, see the Setup Guide. OAuth 2.0 Framework Ramp implements the OAuth 2.0 authorization framework with the following components: Resource Server: Ramp's API endpoints that serve protected resources Authorization Server: Ramp's OAuth service that issues access tokens Client: Your application requesting access to Ramp resources Resource Owner: The Ramp business granting access to their data Client Credentials Internal integrations, server-to-server None required Authorization Code Third-party apps, public integrations Admin consent required Permission Model & Scopes Ramp's permission model uses OAuth 2.0 scopes to control access to different resources and operations. Each scope follows the pattern resource:permission where: resource: The API resource (e.g., transactions, bills, users) permission: The allowed operation (read or write) accounting:read Accounting data Access accounting sync status and metadata applications:read Applications View financing application status applications:write Submit and manage financing applications accounting:write Update accounting sync settings and connections bank_accounts:read Bank accounts View connected bank account information bills:read Bills Access bill data and payment history bills:write Create, update, and pay bills business:read Business profile Access business information and settings cards:read Cards View card information and spending limits cards:read_vault Card vault Access sensitive card data (PAN, CVV) cards:write Create, update, and manage cards cashbacks:read Cashback rewards View cashback earnings and history custom_records:read Custom records Access custom data fields and records custom_records:write Create and update custom data fields departments:read Departments View department structure and assignments departments:write Create and manage departments entities:read Legal entities Access entity information and hierarchies item_receipts:read Item receipts View itemized receipt data leads:read Sales leads Access lead and referral information leads:write Create and update lead information limits:read Spending limits View spending limits and policies limits:write Create and modify spending limits locations:read Locations View location data and assignments locations:write Create and manage location data memos:read Memos Access transaction memos and notes memos:write Add and update transaction memos merchants:read Merchants View merchant information and policies purchase_orders:read Purchase orders Access purchase order data and status receipt_integrations:read Receipt integrations View receipt integration settings receipt_integrations:write Configure receipt integration settings receipts:read Receipts Access receipt images and data receipts:write Upload and manage receipt data reimbursements:read Reimbursements View reimbursement requests and status spend_programs:read Spend programs Access spend program configuration spend_programs:write Create and manage spend programs statements:read Statements Download monthly statements transactions:read Transactions Access transaction data and history transfers:read Transfers View transfer history and status users:read Users Access user profiles and roles users:write Create and manage user accounts vendors:read Vendors View vendor information and payment details vendors:write Create and update vendor information When requesting scopes for your application: Principle of Least Privilege: Only request scopes your application actually needs Read vs Write: Start with read-only access and add write permissions as needed Sensitive Data: Scopes like cards:read_vault require additional security review Related Resources: Some operations may require multiple scopes (e.g., creating cards may need both cards:write and users:read) Token Management Access tokens issued by Ramp have the following characteristics: Format: Opaque tokens (not JWT) Lifetime: 10 days (864,000 seconds) for Client Credentials Scope Binding: Tokens are bound to specific scopes and cannot be used beyond granted permissions Environment Isolation: Tokens work only in the environment where they were issued Token Security Access tokens provide complete access to granted scopes. Treat them as credentials: Never log tokens or include them in error messages Store tokens encrypted at rest Use HTTPS for all API communications Implement token rotation for long-running applications Monitor for unusual API usage patterns Authorization Flow Deep Dive Best for server-to-server integrations where no user interaction is required. When to Use: Internal company integrations Backend services accessing Ramp data Automated workflows and data sync Security Considerations: Client secret must be kept secure and never exposed in client-side code Suitable for confidential clients (servers, not mobile apps or SPAs) No user context - operates with the permissions of the app creator Required for third-party applications and public integrations. Use this flow if you're building a public integration or need users to explicitly grant access to their Ramp accounts. This flow is required for third-party applications acting on behalf of other businesses (e.g. apps listed on ramp.com/integrations). Third-party integrations Multi-tenant applications Apps requiring user-specific permissions Requires HTTPS redirect URIs State parameter must be cryptographically random and verified Authorization codes have short lifetimes (10 minutes) Only Admin and Business Owner users can grant authorization Step 1: User is redirected to Ramp authorization URL There are five required parameters in this request: response_type Required — Must be set to code. scope Required — Space-separated list of scopes (e.g., transactions:read business:read). client_id Required — Your app's client ID from the Ramp Developer Console. redirect_uri Required — Must match exactly one of the URIs configured in your app. state Required — Protects against CSRF; should be unique and verifiable by your app. Example URL: Your application must direct the user to Ramp's OAuth authorization endpoint. This initiates the flow by asking the user to log in and approve your app. Step 2: User authenticates and approves access Only users with Admin or Business Owner roles can authorize third-party applications. If a user with insufficient permissions attempts to authorize your app, they will receive a "Business not authorized to use this application" error. The user logs in to Ramp and is shown a screen prompting them to approve your app's requested access. Upon approval, Ramp redirects to your redirect_uri with a temporary code and the original state: Extract the code from the URL to proceed to token exchange. Step 3: Exchange the code for an access token Step 4: Refresh the access token Tokens expire. Use the refresh token to obtain a new access token: Error Handling invalid_client Client authentication failed Verify client ID and secret are correct invalid_grant Authorization code expired or invalid Restart authorization flow with new code invalid_scope Requested scope not configured for app Update app configuration or request different scopes unauthorized_client Grant type not enabled for this client Enable required grant type in app settings access_denied User denied authorization request User must approve access or contact admin When using access tokens with API endpoints: 401 Unauthorized: Token is missing, expired, or invalid 403 Forbidden: Token is valid but lacks required scope for the resource 429 Too Many Requests: Rate limit exceeded (see Rate Limiting) FAQ Need help? Submit a Developer API support ticket and our team will follow up. Review the API endpoints your app will use. Each endpoint's documentation lists required scopes. Start with read-only scopes and add write permissions as needed. No, each environment requires separate app configurations. Create one app in sandbox for testing and another in production for live usage. For security reasons, only users with Admin or Business Owner roles can grant OAuth2 permissions to third-party applications. This ensures proper oversight of data access. Access tokens last 10 days. Implement refresh logic before expiration rather than waiting for 401 errors. For long-running applications, refresh tokens daily or when starting new sessions. The authorization server will return an invalid_scope error. Configure all required scopes in your app settings before requesting them in authorization flows. No, scopes are bound to tokens at issuance time. To change scopes, you must obtain a new access token with the updated scope configuration. Only users with Admin or Business Owner roles can authorize third-party applications Ask your customer to have an Admin or Business Owner complete the authorization flow Regular users cannot grant OAuth2 permissions for security reasons The customer should verify their role in Settings > Team Admin and Business Owner roles are clearly labeled in the Ramp UI If uncertain, they should contact their Ramp administrator --- title: Bill Pay source_url: /developer-api/v1/bill-pay text_url: /llms-guides/bill-pay.txt summary: A bill is the structured accounts payable record in Ramp—the object that powers approvals, coding, and payment. content: A bill is the structured accounts payable record in Ramp—the object that powers approvals, coding, and payment. For product details, see the Ramp Help Center. ERP integration: Sync bills and payments between Ramp and your accounting system Bill processing automation: Programmatically create bills that are automatically approved for payment Financial reporting: Extract bill and payment data for custom reporting and analytics How Bills Work Payments are nested within bills and do not have their own dedicated endpoints. When you create a bill via API, you include payment details in the same request. Payment info is returned as part of the bill object on GET /bills. Payments can be created alongside bills, but have limited support for updates once created. Bills move through the following statuses: Draft → Invoice uploaded, OCR extracts details Pending approval → Awaiting approver sign-off Approved → Ready for payment. Bills follow your customer's configured approval policy in Ramp. Paid → Payment processed Bills created via API are automatically approved and enter the workflow at the Approved status. Draft bill endpoints We have draft bill endpoints available to create and update draft bills through the API. Draft bills must be approved through the Ramp dashboard—approval via API is not supported. Submit a Developer API support ticket for early access. Create Bill Request Builder Use the POST /bills endpoint to create a bill. This covers the entire bill object, including the bill payment. The request requires several UUIDs. Fetch these from the endpoints below and use the response field value as the value for the request field. GET /entities id entity_id bank_accounts[].id where usage_type = BILL_PAY_BANK_ACCOUNT source_bank_account_id GET /vendors vendor_id GET /vendors/{id}/contacts vendor_contact_id GET /vendors/{id}/accounts id (for ACH/wire/SWIFT only) vendor_account_id Missing BILL_PAY_BANK_ACCOUNT? If you don't see a bank account with usage_type = BILL_PAY_BANK_ACCOUNT in your GET /entities response, Bill Pay hasn't been set up for your organization yet. Follow the steps in the Bill Pay set up guide to configure it, then retry your API call. Upload invoice PDFs or supporting documents using POST /bills/{bill_id}/attachments. This endpoint accepts multipart/form-data. Payment Methods Paying by Ramp Card earns cashback on bill payments. Two options: Existing Ramp Card – Use already-created cards for bill payments. Manually share card details with vendors, then use transaction matching to link the payment to the bill once it clears. Single-Use Virtual Card – Ramp generates a unique virtual card for each bill with the limit set to the bill amount. Two delivery options: Card delivery disabled – Card details become available once the bill is approved; manually share with vendors Card delivery enabled – Ramp automatically emails card details to the vendor's primary contact on the due date, with reminders at 2, 4, and 7 days Single-use cards auto-lock when the spending limit is reached, after 14 days (delivery enabled) or 21 days (delivery disabled). Transaction matching happens automatically once payments clear. Supports international bills in local currency. For programmatic access to full card details (PAN/CVV) or custom spending controls, see the Virtual Cards guide. To filter out one-time card transactions in the Transactions API, set has_no_sync_commit=true. These payment methods require a source_bank_account_id from GET /entities. ACH Verified vendor bank account 2–3 business days Check Vendor address 5–7 business days Wire Same-day (domestic) SWIFT Varies (international) Payments arrive by payment_arrival_date (cannot be a weekend or bank holiday) Non-check payments require a verified vendor bank account via GET /vendors/{id}/accounts. See Create Bill Request Builder for full schema details. Check payments require a vendor address on file Expedited ACH and Wire payments are not available via API Use webhooks to receive real-time notifications when bills are created, approved, rejected, or paid. See our Webhooks Guide for setup instructions. Bills sync automatically with direct accounting connections (QuickBooks, NetSuite, etc.). For custom integrations, see the Accounting guide. Query with sync_ready=true to find bills ready for export. UCSV restriction Bills cannot be synced via API with Universal CSV. Use the dashboard export instead. To verify a bill matches its purchase order and item receipt: Get the bill → extract purchase_order_ids, line_items[].purchase_order_line_item_id, and inventory_line_items[].purchase_order_line_item_id Get the purchase order → extract item_receipt_ids Get the item receipt → confirm line_items[].purchase_order_line_item_id matches the bill When all three documents share the same line item IDs, you have a verified match. Current API Limitations You cannot trigger or manage bill approvals through the API You cannot mark a draft bill as approved or configure approval process logic via API Bills created via API are automatically approved Payments are nested within bills and do not have their own dedicated endpoints Payments can be created alongside bills, but have limited support for updates once created Batch payments (creating a single payment for multiple bills) are not supported OCR upload for draft bills is not currently supported via API Images of invoices cannot be attached through the API Managing entity bank accounts is not supported via API (vendor bank accounts can be managed through vendor accounts endpoints) Submit a Developer API support ticket and our team will follow up. --- title: Build with Ramp source_url: /developer-api/v1/build-with-ramp text_url: /llms-guides/build-with-ramp.txt summary: Ramp enables technology partners to build integrations that reach 50,000+ businesses. This guide walks you through building, testing, and publicly listing on the Ramp Integrations page. content: Ramp enables technology partners to build integrations that reach 50,000+ businesses. This guide walks you through building, testing, and publicly listing on the Ramp Integrations page. Monetize your integration — You keep 100% of your revenue. Set your own pricing, charge customers directly, and grow your business without revenue sharing or platform fees. Public marketplace listing — Your integration gets featured on the Ramp Integrations page, giving you visibility and credibility with prospective customers. This guide applies to all integration categories. Additional guidance for Accounting/ERP integrations is linked where relevant. Building an integration with Ramp means entering a partnership focused on delivering a high-quality experience to our shared customers. Each side plays a clear role in making that happen. Your side: Pricing and monetization — You set your pricing, bill customers directly, and keep 100% of revenue. Ramp does not process payments or participate in billing. Building and hosting your integration — You develop and maintain your integration using Ramp's APIs. Customer support — You assist customers through your own support channels and provide a public support email. Documentation — You host setup guides, workflow instructions, and troubleshooting on your site. Marketing assets — You supply the logo, descriptions, screenshots, and videos for your listing. Ramp's side: API troubleshooting & advisory — Our team helps you debug API issues and offers guidance on best practices and specific use cases. Product review and guidance — We review your integration flows and provide feedback. Approval is required before production access. Distribution — Your integration reaches 50,000+ businesses once approved. This partnership model gives you full ownership of your product while Ramp provides oversight, guidance, and reach. Each integration must go through the following three stages; below is a checklist to help you work your way through each stage. Phase 1: Build Phase 2: Apply for Production Access Phase 3: Beta Testing Phase 4: Apply for a Public Listing Appendix You control your pricing. Ramp does not charge fees or take a revenue share. Many integrations are free, while others charge for their services—the choice is yours. Best practices for pricing: Price relative to the value your integration delivers to customers. Keep pricing predictable and easy to understand. Factor in implementation cost, ongoing maintenance, and support burden. Common pricing models include: Flat annual subscription. Implementation fee plus annual renewal. Usage-based pricing (for example, per transaction or per bill). Tiered feature bundles based on functionality. High-quality documentation improves customer activation and reduces support load. It is also heavily used by Ramp's sales, customer success, and support teams when discussing your integration. Your documentation should: Be publicly accessible and hosted on your website. Include prerequisites for both Ramp and your platform. Provide step-by-step setup instructions. Detail key user workflows and common use cases. Offer troubleshooting tips and a frequently asked questions section. Examples of strong integration documentation: Dualentry Ramp for FE Acumatica Ramp's systems may surface your documentation links when customers and internal teams ask about your integration, so strong docs are one of your most effective marketing and support assets. Partners must fully complete security disclosures and provide: Security certifications and/or attestations such as SOC 2 Type II, ISO 27001, PCI, or a recent third-party penetration test. Full certification and/or pen test reports (not just summary letters). A public URL to your security policy. A dedicated and monitored security contact email address. Written descriptions covering: What data your integration processes and how it is secured. Where and how data is stored. Your data retention policy. Whether and how employees at your company can access customer data. What data your integration processes and how it is secured. Where and how data is stored. Your data retention policy. Whether and how employees at your company can access customer data. Early-stage companies may use a recent third-party pen test in place of full SOC 2 or ISO 27001 certifications, subject to Ramp's review. You own first-line support for your integration. Ramp will route customer questions about your integration to you. Provide a public support email address; this will be visible to customers and used by them to troubleshoot issues. Maintain clear customer-facing documentation for setup, key workflows, and troubleshooting. Provide an internal support guide for Ramp teams that explains how to triage issues, what information to collect, and how to escalate to your team. Example listing If you have questions while building or preparing your submission, submit a Developer API support ticket. --- title: Cards and Funds source_url: /developer-api/v1/cards-and-funds text_url: /llms-guides/cards-and-funds.txt summary: Ramp's Developer API gives you programmatic control over funds, cards, and spending policies to help your teams spend responsibly and track budgets in real time. Whether you're managing departmental budgets, team events, or office expenses, these APIs provide the building blocks for automated spend management. content: Ramp's Developer API gives you programmatic control over funds, cards, and spending policies to help your teams spend responsibly and track budgets in real time. Whether you're managing departmental budgets, team events, or office expenses, these APIs provide the building blocks for automated spend management. What you'll learn: How to create funds with built-in controls using the Limits API How to scale spending policies with reusable templates using the Spend Programs API When to use virtual vs physical cards for different scenarios How Ramp Funds, Cards, and Spend Programs Work Together Here's how these three concepts work together for effective spend management: Funds act as predefined budgets you assign to employees, teams, or initiatives: They can include merchant and category restrictions, as well as expiration controls They can be shared across multiple users or assigned individually Examples: "Marketing Q2 Budget", "Engineering Team Offsite", "Office Supplies - Austin" Cards are the payment methods users spend funds with: Virtual cards are used for online transactions and subscriptions Physical cards are shipped to users for in-person spending Each card draws from its connected fund's available balance Multiple cards can share the same fund, or one card can access multiple funds Card Data Access: Standard API responses return masked card numbers for security. Full 16-digit card numbers and CVVs require additional security review and PCI API access. Submit a Developer API support ticket if your platform needs to process payments directly using full card data. Spend Programs group funds, users, and cards under shared policies. Think of them as "blueprints" that make fund creation faster and more consistent They can enforce consistent spending rules across multiple funds They can enable automated fund provisioning based on employee attributes Examples: "Team Budgets", "Team Offsites", "Professional Services Procurement" Limits Create and manage funds. Funds are automatically linked to virtual cards. limits:read, limits:write Create reusable spending policy templates for consistent fund creation. spend_programs:read, spend_programs:write Issue and manage physical cards. cards:read, cards:write Transactions View spending activity across cards and funds. transactions:read Complete Walkthrough: Managing a Team Offsite We'll walk you through managing a quarterly team offsite to show how spend programs, funds, and cards work together. This scenario covers the complete lifecycle from setup to monitoring. First, create a reusable template for team offsites that can be used across multiple departments: This creates a template that allows spending on meals (category 19), lodging (category 6), and airlines (category 4). Now create a fund for a Q1 Engineering Team Offsite using the template: Before running these commands: Replace the placeholder values ($SPEND_PROGRAM_ID, $USER_ID, etc.) with actual IDs from your Ramp account. The placeholders are formatted for bash compatibility - you can set them as environment variables or replace them directly in the commands. When creating a fund from a spend program, you only need to provide: display_name - Name for this specific fund spend_program_id - ID of the spend program template to use user_id - The initial user who will have access to the fund idempotency_key - Ensures the request isn't duplicated The fund automatically inherits all spending restrictions and policies from the spend program template. If you need to add more team members to the offsite after initial creation, you can add users to the existing fund: This adds the specified users to the fund, giving them access to spend from the shared offsite budget. During the offsite, monitor spending across both your funds and cards: After the offsite, review spending and close out the budget: Best Practices Create spend programs for recurring spending patterns (travel, SaaS, office supplies) Use descriptive names and appropriate icons for easy identification Set up automatic provisioning rules for standardized employee benefits Enable requestable programs for ad-hoc spending needs Use descriptive display names that indicate purpose Set appropriate spending categories to prevent misuse Enable reimbursements for general expense funds Disable reimbursements for subscription-specific funds Create separate funds for each subscription or vendor Use category restrictions to ensure appropriate spending Set reasonable spending limits based on expected usage Issue physical cards for employees who need in-person spending capability Physical cards can draw from multiple funds through auto-matching Consider shipping time when planning physical card rollouts Regularly review fund balances and spending Suspend funds immediately when no longer needed Use spending categories to limit where funds can be used Data Relationships Spend Programs → Templates for creating multiple similar funds Limits (Funds) → Spending allocations that can have multiple users Cards → Payment methods that can spend from funds Transactions → Spending events that occur on cards against funds FAQ: Cards and Funds Need help? Submit a Developer API support ticket and our team will follow up. Create separate spend programs for different scenarios with distinct spending policies: Team Offsites - meals, entertainment, team activities Travel Expenses - flights, hotels, transportation Conference Attendance - registration, meals, networking events This allows you to set appropriate category restrictions and spending limits for each scenario. Yes! Team members can: Use virtual card numbers from the shared fund for online purchases Use their existing physical cards, which will auto-match to the fund if categories align Get new physical cards issued specifically for the event (as shown in Step 3) The fund acts as the spending pool that multiple payment methods can draw from. Transactions outside allowed categories (meals, entertainment, office supplies in our example) will be declined. You can: Update the spend program or fund to allow additional categories Have team members request reimbursements for valid expenses that don't fit categories Issue separate cards with broader restrictions for specific team members Use the monitoring approach from Step 4: Check fund balances with GET /developer/v1/limits/$LIMIT_ID Filter transactions by fund with GET /developer/v1/transactions?spend_limit_id=$LIMIT_ID Set up webhooks for real-time transaction notifications Use date ranges to track spending during specific event periods For team offsites, use one shared fund (is_shareable: true) because: Easier budget management and monitoring Team members can coordinate spending without individual limits Simplified reporting and reconciliation Virtual card numbers can be shared for online group purchases Use separate funds when individuals need distinct budgets or spending restrictions. Yes - You can create funds (limits) without any associated cards. These funds can be used for reimbursements only. Yes - Physical cards can be created with their own spending restrictions independent of any limit. However, virtual cards are always created as part of a limit. No - Physical cards can have independent spending restrictions OR draw from limits. Virtual cards are always associated with limits. No - Limits can exist for reimbursement-only scenarios without any card numbers. Suspending a Limit: Does NOT automatically suspend associated cards Prevents new spending from the limit Cards linked to the limit will be declined when trying to spend from that limit Cards can still spend from other non-suspended limits (if linked to multiple) Suspending a Card: Prevents ALL spending on that specific card Does NOT affect the associated limits Other cards linked to the same limits can continue spending Terminating a Limit: Permanently disables spending from that limit Does NOT automatically terminate associated cards Cards remain active but cannot spend from the terminated limit Terminating a Card: Permanently disables the specific card Does NOT affect associated limits Other cards can continue spending from the same limits Use spend programs when: You run similar events regularly (quarterly offsites, monthly team dinners) You want consistent spending policies across departments You need templates for employee self-service requests Create funds directly when: This is a one-off event with unique requirements You need custom spending restrictions not covered by existing programs You're testing new spending policies before creating a template Getting Started - API authentication and setup Virtual Cards - For access to full card data including 16 digit card numbers and CVVs Webhooks - Get notified of spending events Limits API - Complete API reference Spend Programs API - Complete API reference --- title: Changelog source_url: /developer-api/v1/changelog text_url: /llms-guides/changelog.txt summary: Stay up to date with our latest API updates via RSS feed (reader required). content: Stay up to date with our latest API updates via RSS feed (reader required). March 30, 2026 March 25, 2026 March 19, 2026 March 18, 2026 March 17, 2026 March 16, 2026 March 12, 2026 February 27, 2026 February 13, 2026 February 12, 2026 February 11, 2026 February 10, 2026 February 5, 2026 February 3, 2026 January 30, 2026 January 28, 2026 January 22, 2026 January 16, 2026 January 14, 2026 January 6, 2026 January 5, 2026 December 23, 2025 December 11, 2025 December 4, 2025 November 28, 2025 November 26, 2025 November 24, 2025 November 20, 2025 November 18, 2025 November 12, 2025 November 10, 2025 November 7, 2025 November 4, 2025 October 31, 2025 October 30, 2025 September 25, 2025 August 8, 2025 June 25, 2025 May 16, 2025 April 29, 2025 March 25, 2025 February 25, 2025 January 17, 2025 May 2024 New List Bank Accounts endpoint — Retrieve a paginated list of bank accounts associated with your business. Supports start and page_size query parameters for pagination. View endpoint New List Vendor Agreements endpoint (beta) — Query vendor agreements with extensive filtering options including date ranges, renewal status, contract owners, departments, total value, and custom record filters via POST /developer/v1/vendors/agreements. View endpoint Enhanced vendor filtering by timestamps — Added to_created_at, from_updated_at, and to_updated_at query parameters to the List Vendors endpoint for filtering vendors by creation and update dates. View endpoint Vendor subsidiary data — Added include_subsidiary query parameter to the List Vendors endpoint. When set to true, vendor responses include a subsidiary field with ERP subsidiary identifiers. View endpoint Allowed overage percent override on limits — The allowed_overage_percent_override field is now available when creating limits and is returned in limit responses. This decimal value (0–100) lets you set a fund-level override for the allowed overage percent, independent of the spend program or business default. View endpoint Update custom accounting field options — New PUT /developer/v1/accounting/field-options/{field_option_id} endpoint to update existing custom accounting field options. View endpoint New audit log event types — Added Generated renewal brief for contract, Spend allocation change request approval policy updated, and Vendor Network updates enabled event types to the audit logs endpoint. Updated token prefix format — Access tokens are now prefixed with ramp_business_tok_, ramp_user_tok_, ramp_business_jwt_, or ramp_user_jwt_ instead of the previous ramp_tok_ prefix. Refresh tokens use ramp_business_tok_ or ramp_user_tok_. Custom records reference columns relaxed — The corresponding_column_name field on reference column configurations is no longer required and defaults to null. It will be auto-generated if not provided, simplifying forward-only reference column setup. Auto-match uploaded receipts without a transaction ID — The POST /receipts endpoint can now automatically match uploaded receipts to transactions without requiring a transaction_id. View endpoint New financing applications endpoints (beta) — Create and fetch financing applications programmatically. Submit applicant details, business information, controlling officers, beneficial owners, and financial details. View GET endpoint | View POST endpoint | View guide New ready-to-sync endpoint (beta) — Mark accounting objects as ready to sync by providing a list of object_ids and an object_type (currently supports TRANSACTION). View endpoint New applications.status_updated webhook event — Subscribe to applications.status_updated to receive notifications when a financing application's status changes. View endpoint New bill payment status ON_HOLD — Added ON_HOLD enum value to the bill payment_status filter and response, representing bills that have been placed on hold. View endpoint New cancelled trip status — The status filter on the List Trips endpoint now supports the cancelled enum value, and trip responses can include cancelled as a status. View endpoint New audit log event type — Added Vendor linked to vendor network to the list of supported audit log event types. View endpoint New GL account classification types — Added AR_CHARGEBACK_CLEARING_ACCOUNT and AR_REFUNDS_CLEARING_ACCOUNT classification enum values for accounting GL accounts. New bill filtering by payment ID — Added customer_friendly_payment_id query parameter to filter bills by their customer-friendly payment identifier, making it easy to find all bills belonging to the same payment or batch payment. The response also now includes customer_friendly_payment_id on bill payment objects. View endpoint New bill filtering by draft bill ID — Added draft_bill_id query parameter to the List Bills endpoint to filter by the originating draft bill. The bill response now also includes draft_bill_id to indicate which draft bill a bill was created from. View endpoint New bill and draft bill filtering by remote ID — Added remote_id query parameter to both the List Bills and List Draft Bills endpoints, allowing you to look up bills and drafts by their external system identifier. View endpoint | View draft bills endpoint Reactivate deleted inventory item options — Added reactivate field to the PATCH /developer/v1/accounting/inventory-item/options/{option_id} request body, bringing parity with custom field options by letting you restore soft-deleted inventory item options. View endpoint Vendor owner is now optional — The vendor_owner_id field is no longer required when creating a vendor via POST /developer/v1/vendors. Omitting it creates the vendor without an owner. View endpoint Decimal quantity support for bill line items — The unit_quantity field has been replaced with quantity, which now accepts decimal values (e.g., 2.25) instead of only integers. unit_quantity is still accepted for backwards compatibility. The unit_price field also now accepts decimal string or number formats. This applies when creating or updating line items on bills and draft bills. View endpoint New GL account classification types — Added six new enum values for GL account classifications: AR_ACCOUNTS_RECEIVABLE_ACCOUNT, AR_BAD_DEBT_ACCOUNT, AR_CARD_FEES_ACCOUNT, AR_CASH_ACCOUNT_DEFAULT, AR_INCOME_ACCOUNT_DEFAULT, and AR_UNDEPOSITED_FUNDS_ACCOUNT, enabling accounts receivable accounting integrations. Vendor memo support for bills — Added vendor_memo field to create and update bill endpoints, as well as draft bill endpoints, allowing you to set a memo to the vendor (up to 400 characters) on a bill. View endpoint | View endpoint | View endpoint | View endpoint Refresh token expiration info — The token endpoint response now includes a refresh_token_expires_in field indicating how long the refresh token is valid (in seconds), making it easier to manage token lifecycle for clients configured with a refresh token TTL. View endpoint New embedded cards endpoint (beta) — Generate an embed init token for a card to enable embedded card experiences in your application. Requires the embedded_cards:write scope and the card must be activated and active. View endpoint New audit log event type — Added RFX graded to the list of supported audit log event types, allowing you to track when an RFX has been graded. View endpoint Global library field ID on custom record columns — Custom record column responses now include a global_library_field_id field, letting you identify columns that are linked to global library fields. Visibility filter for accounting field options — Filter custom accounting field options by visibility (HIDDEN or VISIBLE) using the new visibility query parameter. View endpoint Bill filtering by ERP sync status — Filter bills by whether they are configured to sync to your ERP using the new is_accounting_sync_enabled query parameter. View endpoint Payment accounts on entities — The entity response now includes a payment_accounts array containing bank accounts eligible for bill payment, with details like account_name, account_number_last_four, currency, and id. View endpoint Custom record fields on vendors — Vendor responses now include a custom_record_fields array with column metadata, display values, and reference row details for custom record data associated with each vendor. View endpoint Policy agent exemption for spend limits — Spend limit responses now include is_exempt_from_policy_agent, and you can update it via PATCH along with existing_expense_policy_agent_exemption_application_rules to control whether the exemption applies retroactively (APPLY_TO_ALL) or only to future transactions (APPLY_TO_NONE). View endpoint Accounting vendor creation flag on transactions — Transaction responses now include requires_accounting_vendor_creation_to_sync, indicating whether your integration must create an accounting vendor before syncing the transaction. View endpoint New webhook event types for unified requests — Added unified_requests.created, unified_requests.modified, unified_requests.node_advanced, unified_requests.override_approved, and unified_requests.updated to the list of subscribable webhook events. View endpoint New transaction decline reasons — Added AUTHORIZER_SPEND_ALLOCATION_MEMBER_SUSPENDED and AUTHORIZER_UNAUTHORIZED_USER enum values for more granular transaction decline details. New custom records reference table types — Added contracts and purchase_order_line_items as valid native reference table types for custom record columns. New custom record text display type — Added numeric_id to the available display types for custom record text columns. New audit log event types — Added ABK agent blocked on user, ABK agent review requested, ABK agent started, Document labeled, Edited contract tracking setting, and Reimbursement bank account updated for more comprehensive audit trail coverage. View endpoint New spend program mapped field type — Added REQUEST_REASON as a mapped field option for spend program configurations. New vendor document types — Added INVOICE and VENDOR_CREDIT to the list of supported vendor document types. Filter bills by payment ID — Added payment_id query parameter to the List Bills endpoint, letting you retrieve all bills belonging to the same batch payment. View endpoint Payment ID on bill responses — Bill payment details now include an id field representing the unique payment identifier. Bills sharing the same payment ID belong to the same batch payment. Draft bill attachment uploads — Upload file attachments to existing draft bills via POST /developer/v1/bills/drafts/{draft_bill_id}/attachments, using multipart/form-data. View endpoint Bank account ID on transfers — Transfer responses now include a bank_account_id field containing the UUID of the bank account used for the transfer payment (or null for wire transfers). Use GET /developer/v1/bank-accounts/{bank_account_id} to look up account details. View endpoint Vendor creation on sync setting for accounting connections — Added transaction_accounting_vendor_creation_on_sync_enabled to accounting connection settings. When enabled, card transactions missing a mapped accounting vendor will require vendor creation before sync. Available on create and update endpoints. View endpoint New INVOICE sync resource type — Added INVOICE as a supported enum value for accounting sync resource types, expanding the types of records you can sync through accounting connections. New webhook event types — Added bills.archived and reimbursements.batch_payment_reimbursed to the list of supported webhook event types, so you can subscribe to notifications when bills are archived or batch reimbursement payments are processed. View endpoint Scheduled deactivation date for new users — Added scheduled_deactivation_date field to the create user request. For guest users, this automatically defaults to 6 months from the invite creation date unless explicitly set to null. View endpoint Date column type for custom records — Custom record tables now support a datetime column type with date display, allowing you to store and display date values in custom and matrix tables. Attachments on custom form fields — Custom form field responses now include an attachments array containing document metadata with download URLs, filenames, and version information. New transaction decline reason — Added AUTHORIZER_SPEND_ALLOCATION_ARCHIVED_FUNDS enum value to transaction decline reasons, indicating a transaction was declined because the associated funds are archived. New OAuth scope — Added comments:write scope for granting write access to comments. New status_summary field on bills — Bill responses now include a status_summary field that provides a more granular view of a bill's lifecycle stage, with values like PAYMENT_SCHEDULED, APPROVAL_PENDING, PAYMENT_PROCESSING, PAYMENT_COMPLETED, and more. This gives you richer insight into exactly where a bill stands beyond the existing OPEN/PAID status. View endpoint Enhanced bill filtering by status_summary — The status_summary query parameter on the List Bills endpoint now uses a refined set of enum values (removing draft-related statuses like DRAFT_MISSING_INFO, DRAFT_PARSING, DRAFT_QUEUED, and DRAFT_READY) to filter bills by their detailed status. View endpoint New NON_ERP accounting field type — Added NON_ERP as a new enum value for accounting field types, allowing you to distinguish fields that are not sourced from an ERP system. View endpoint Clarified currency amount representations for bills and purchase orders — Documentation for amount fields on bills and purchase order line items now specifies that values are represented in the lowest denomination of the currency (e.g., cents for USD), making it easier to correctly interpret amount and unit_price fields. Filter limits by card — Added card_id query parameter to the List Limits endpoint, letting you filter for limits linked to a specific card. View endpoint Draft bill remote_id field — The draft bill response now includes a remote_id field, providing the external ID that identifies the bill on the client's side. View endpoint Custom Records column display types — Number columns now support a display_type field with values currency, number, and percentage. Text columns now support a display_type field with values email, paragraph, phone, plain_text, and url, giving you more control over how column data is presented. New endpoint to fetch accounting connection by ID (beta) — Retrieve details for a specific accounting connection using its connection_id. View endpoint Renamed tax code options request field — The POST /developer/v1/accounting/tax/code/options endpoint now uses options instead of tax_codes as the request body field name for uploading tax code options. View endpoint New item_receipts.created webhook event — Subscribe to item_receipts.created events to get notified when new item receipts are created. View endpoint Transaction functional_currency_amount moved behind query parameter — The functional_currency_amount field is no longer returned by default on transactions. Specify it via a query parameter to include the entity's functional currency amount in the response. View endpoint New tax code options management (beta) — Upload, list, update, and delete tax code options for accounting connections with filtering by remote_id, is_active, and code. View endpoints Enhanced vendor filtering — Added merchant_id query parameter to the List Vendors endpoint for filtering by associated card merchants. View endpoint Draft bill creation and updates — Create and update draft bills with support for accounting fields, line items, and vendor details. View endpoint Bills now include item receipt associations — Added item_receipt_ids field to bill responses showing linked item receipts from matched purchase orders. Accounting connection migration status — Added is_ready_to_migrate field to accounting connections indicating readiness for ERP migration workflows. New inventory item accounting field endpoints (beta) — Create, read, update, and delete inventory item accounting fields for tracking inventory items in your ERP system. View field endpoint Inventory item options management (beta) — Upload, list, update, and delete inventory item options with filtering by remote_id, is_active, code, and is_synced. View options endpoint New tax code accounting field endpoints (beta) — Create, read, update, and delete tax code accounting fields for managing tax codes in your ERP system. View endpoint Transaction sync button setting — Added transaction_sync_button_enabled setting to accounting connections for enabling manual transaction sync functionality in API-based integrations. Extended accounting field requirements — Added VENDOR_CREDIT enum value to is_required_for arrays in accounting fields, allowing fields to be required for vendor credit objects. New vendor awarded audit event — Added Vendor awarded event type to audit logs for tracking vendor award actions. Enhanced transaction data — Added functional_currency_amount field to transaction responses, showing the transaction amount in your entity's functional currency when an ERP with functional currency is configured. View endpoint Tax rate field renamed — The gl_account_id field in tax rate resources has been renamed to accounting_gl_account_id for better clarity across accounting tax rate endpoints. View endpoint New tax rates endpoints (beta) — List, upload, update, and delete tax rates for accounting integrations with support for up to 500 tax rates per batch upload. View list endpoint and View upload endpoint Enhanced bill creation — Added use_default_vendor_contact parameter to automatically use the vendor's default contact when creating bills, making vendor_contact_id optional. View endpoint Ramp category code enums — Category fields now include explicit enum values and descriptions for all Ramp category codes (1-44) across transactions, vendors, cards, and spending restrictions for better validation and documentation. New audit log event types — Added RFX (Request for X) and sourcing event types to audit logs including RFX creation, vendor management, clarification processes, and sourcing event status changes. New purchase order line item management (beta) — Add, update, and delete line items on existing purchase orders. View add endpoint, View update endpoint, View delete endpoint New card vault endpoint (beta) — Retrieve sensitive card details by card ID for vault API access holders. View endpoint Default payment method support for bills — Added use_default_payment_method parameter to create bills using vendor's configured default payment method. View endpoint Enhanced vendor data — Added code field to accounting vendors for ERP system vendor codes. Item receipt line item tracking — Added id field to item receipt line items and item_receipt_line_item_ids arrays to bill line items and bill inventory line items for better purchase order tracking. New audit log event types — Added AI custom field config executed, External ticket created zendesk, and User previewed event types. New webhook events — Added purchase_orders.archived, reimbursements.sync_requested, and transactions.sync_requested webhook event types. Additional managed portfolio accounts — Added new managed portfolio account types: MANAGED_PORTFOLIO_INTEREST_INCOME_ACCOUNT, MANAGED_PORTFOLIO_POSITION_ASSET_ACCOUNT, MANAGED_PORTFOLIO_REALIZED_GAIN_LOSS_ACCOUNT, and MANAGED_PORTFOLIO_UNREALIZED_GAIN_LOSS_ACCOUNT. Enhanced item receipts filtering — Added query parameters for filtering item receipts by entity_id, purchase_order_id, and purchase_order_line_item_id, plus include_archived option to include archived receipts and standard pagination with start and page_size. View endpoint New currency support — Added USDB currency code for USD Basecoin across all endpoints that support currency values. New audit log event types — Added support for tracking blank canvas workflow pause status updates, contract combinations, SFTP authentication events, and vendor management expansion request changes in audit logs. Enhanced user management — Added scheduled_deactivation_date field to user objects for scheduling automatic user deactivation on a specific date. View endpoint New SFTP configurations resource type — Added SFTP Configurations as a supported resource type in audit logs for tracking SFTP-related configuration changes. Enhanced bill filtering — Added status_summaries query parameter to filter bills by multiple status summaries like APPROVAL_PENDING, PAYMENT_COMPLETED, or DRAFT_READY. View endpoint Tracking category metadata in custom records — Custom record accounting field options now include a tracking_category object with metadata like display name, active status, and accounting provider connection status alongside the existing tracking_category_uuid. New accounting connection update endpoint (beta) — Update settings for API-based accounting connections, including vendor credits configuration. View endpoint Enhanced reimbursement filtering — Added state query parameter to filter reimbursements by status including APPROVED, AWAITING_EXPORT, PENDING, REIMBURSED, and other states. View endpoint New vendor credits endpoints (beta) — Retrieve vendor credits across all vendors or for specific vendors with filtering by accounting dates and usage status. View endpoint Individual vendor credit retrieval (beta) — Fetch detailed information about a specific vendor credit including line items, applied bills, and remaining amounts. View endpoint Vendor-specific credit listing (beta) — List vendor credits for a specific vendor with the same filtering options as the global endpoint. View endpoint New audit log event types — Added Card delivered, Reimbursement submitted, Reimbursements disabled, and Reimbursements enabled event types for enhanced audit tracking. Custom form comments support — All custom form field responses now include an optional comment field for additional context on responses. Enhanced custom form entity support — Added vendors to the list of supported entity types for custom forms alongside existing entities like bills, users, and transactions. New webhook event — Added spend_requests.comment_created event type for webhooks to notify when comments are created on spend requests. Enhanced custom records relationships — Added relationship metadata to tracking category fields in custom record line items for improved data linking between tracking categories and custom field options. Custom records tracking category requirement — Added tracking_category_uuid as a required field for native reference column types in custom records, enabling better integration with accounting field options. Multiple purchase orders per bill — Bills can now be linked to multiple purchase orders using the purchase_order_ids array field in both create and update operations, replacing the previous single purchase_order_id field. View endpoint ERP migration tool (beta) — Set up a new API-based accounting connection to seamlessly migrate from your current ERP to a new one. View guide Enhanced bills filtering — Added invoice_number query parameter to filter bills by exact invoice number. View endpoint Enhanced receipts filtering — Added reimbursement_id query parameter to filter receipts for a specific reimbursement. View endpoint Enhanced users filtering — Added status query parameter to filter users by status (USER_ACTIVE, USER_INACTIVE, USER_SUSPENDED), replacing the deprecated include_deleted parameter. View endpoint Enhanced accounting field filtering — Added is_active and code query parameters for filtering custom accounting fields and field options by active status and code. View endpoint New vendor bank account archiving — Archive vendor bank accounts with automatic transfer of associated bills, drafts, and recurring templates to a replacement account. View endpoint New currency support — Added CNH (Chinese Yuan Renminbi offshore) to supported currencies across bill and purchase order endpoints. New DATE input type — Added DATE enum value for custom accounting field input types, supporting ISO format (YYYY-MM-DD) in free form text fields. Enhanced audit log events — Added new vendor management agreement event types including document operations (deleted document, linked document, uploaded document) and purchase order operations (linked purchase order, unlinked purchase order). Enhanced attachment types — Added EMAIL and VENDOR_CREDIT enum values for bill attachment types. Provider name fields — Added provider_name field to custom accounting fields, field options, GL accounts, and vendors to identify the accounting connection source. Reimbursement payment tracking — Added payment_batch_id field to reimbursements for tracking payment batch associations. Enhanced vendor filtering — Added external_vendor_id query parameter to filter vendors by customer-defined external identifiers, independent of accounting system remote IDs. View endpoint External vendor ID support — Added external_vendor_id field to vendor creation, updates, and responses for tracking customer-defined identifiers separate from accounting system remote IDs. View endpoint Purchase order line item matching — Added purchase_order_line_item_id field to bill line items for tracking matched purchase order line items. View endpoint Real-time payment support — Added RTP enum value for Real-Time Payment processing method. Same-day bill payments — Added is_same_day parameter to enable same-day delivery for eligible ACH payments when creating bill payments. View endpoint Spend program line item fields — Added line_item_accounting_fields to spend program responses, showing custom accounting fields enabled for line items in each program. View endpoint New audit log event — Added Vendor management agreement notification type switched event type for vendor management tracking. Form 1099 compliance type — Added FORM_1099 enum value to vendor compliance types for tax reporting requirements. Enhanced date filtering — Improved transaction filtering parameters with explicit ISO8601 format specification for synced_after, from_date, and to_date parameters. View endpoint Draft bill tracking — Added draft_bill_created_at field to bill responses for tracking when bills were originally created as drafts. View endpoint Delete matrix table rows — Remove individual rows from custom matrix tables using the delete endpoint. View endpoint Matrix table row IDs — Matrix table rows now include an id field for unique identification and row-level operations. Number column support for custom tables — Create and use number columns in custom tables with the new number column type for numerical data storage. Default entity for vendors — Added default_entity_id field to vendors for associating a default business entity with vendor records. New procurement event type — Added Procurement agent run completed enum value for audit log events tracking procurement automation completion. New limited edition card designs — Added holiday-themed card design options including limited_edition_gifts, limited_edition_gingerbread_man, limited_edition_grinch, limited_edition_hot_cocoa, limited_edition_reindeer, limited_edition_santa, and limited_edition_snowman enum values for card customization. Bill accounting sync control — Added enable_accounting_sync boolean field to bill responses that indicates whether the bill should sync to the ERP system. View endpoint Manual vendor payment method — Added MANUAL enum value to vendor payment method kind field for manually processed payments. New accrual AP account type — Added ACCRUAL_AP_ACCOUNT enum value for accrual accounts payable account usage type. Enhanced custom field values — Custom field values now support number type in addition to boolean and string types. Enhanced bill creation — Added enable_accounting_sync field to control whether bills sync to your ERP system, with additional validation when using remote_id. View endpoint Matrix table column management (beta) — Add result columns to existing matrix tables without modifying input columns via POST /developer/v1/custom-records/matrix-tables/{table_name}/columns. View endpoint Matrix table column renaming (beta) — Change the API name of matrix table columns while preserving human-readable labels via PATCH /developer/v1/custom-records/matrix-tables/{table_name}/columns/{column_name}. View endpoint Number column support for matrix tables (beta) — Matrix tables now support number input columns in addition to reference columns, enabling numeric thresholds and values in matrix configurations. Enhanced vendor data — Vendor accounts now include accounting_connection_id field to identify which accounting connection the vendor is associated with. View endpoint New audit log events — Added "Vendor management agreement status changed" and "Vendor management edited agreement field" event types for tracking vendor agreement modifications. New audit log event type — Added Created fund from purchase order enum value to track fund creation events from purchase orders in audit logs. Enhanced user filtering — Added COORDINATOR role to user role filtering options for better user management capabilities. View endpoint New accounting sync type — Added REPAYMENT_SYNC enum value for repayment synchronization via the object sync endpoint. View endpoint Update purchase order support (beta) — Update existing purchase orders with new accounting field selections, line items, and spend date ranges via PATCH /developer/v1/purchase-orders/{purchase_order_id}. View endpoint Change custom table row external key (beta) — Update the external key identifier for existing custom table rows via PATCH /developer/v1/custom-records/custom-tables/{custom_table_name}/rows/{row_id}. View endpoint Enhanced bill payment methods — Added LOCAL_BANK_TRANSFER payment method for creating bill payments alongside existing options like CHECK, DOMESTIC_WIRE, and SWIFT. Flexible accounting field selections — Accounting field selections now support free_form_text as an alternative to field_option_external_id, allowing custom text values when predefined options aren't available. Improved quantity handling — Line item quantity fields now use number type instead of integer for more precise quantity tracking across bills, purchase orders, and item receipts. Enhanced user validation — Added 50-character limits for first_name and last_name fields, and minimum length validation for vendor names to ensure data quality. New trips endpoints (beta) — List all trips for your business with filtering by user IDs, status, date ranges, amount ranges, and trip names, or fetch individual trips by ID. Includes trip details like locations, spend events, total spend, and travel types. List trips | Get trip Enhanced custom records matrix filtering — Added filters parameter to filter matrix table rows by input column values using the new column filter structure with column_name and one_of matching. View endpoint Enhanced entity filtering — Added hide_inactive parameter to entity endpoints to filter out inactive entities. View endpoint New workflow base type — Added Workflow (Base) enum value for custom record types to distinguish base workflow configurations from standard workflows. Enhanced bill filtering by payment date — Added from_payment_date and to_payment_date parameters to the List Bills endpoint for filtering bills by their payment dates. View endpoint New Matrix tables for Custom Records (beta) — Create and manage lookup tables where unique input combinations map to result values, with endpoints for table creation, row management, and cell operations. View endpoints Enhanced spend program details — The Get Spend Program endpoint now includes custom_form_collection for form requirements and expanded response schema with detailed program information. View endpoint New vendor default payment method — Added default_payment_method field to vendor responses, showing the configured payment policy and update source for each vendor. Enhanced vendor filtering — Added accounting_vendor_remote_ids and vendor_tracking_category_option_ids query parameters to the List Vendors endpoint for filtering by accounting integration data. View endpoint New audit log event types — Added Agent access request resolved, Agent access requested, and Set member limit on shared fund event types for tracking agent access workflows and shared fund member limits. API Updates and Improvements New audit logs endpoint (beta) — Retrieve audit log events with filtering by user IDs, date ranges, event actor types, and event types. Supports pagination and comprehensive event history tracking. View endpoint Enhanced transaction filters — Added has_been_approved, all_requirements_met_and_approved, and has_statement parameters to filter transactions by approval status, requirements completion, and statement presence. The sync_ready parameter is now deprecated in favor of using sync_status with SYNC_READY. Enhanced user endpoints — Added include_deleted parameter to include deleted users in list responses. Enhanced reimbursements filtering — Added has_been_approved parameter to filter reimbursements by approval status. Enhanced purchase orders filtering — Added spend_request_id parameter to filter purchase orders by associated spend request. New accounting sync type — Added AMORTIZATION_ENTRY_SYNC enum value for amortization entry synchronization. New payment method type — Added CRYPTO_WALLET_TRANSFER enum value for cryptocurrency wallet transfers across bills, reimbursements, and transactions. Enhanced spend limit creation — Added accounting_rules parameter to set accounting rules when creating or updating spend limits and vault cards. Enhanced accounting connections — Updated description for creating accounting connections to clarify Universal CSV connection upgrade behavior, and added connection_type field showing connection type details. Vault cards endpoint publicly available — Create virtual cards through the vault endpoint. View endpoint Bill attachment upload support — Upload attachments to existing bills via POST /developer/v1/bills/{bill_id}/attachments. View endpoint Allow negative line items for bill creation — Bills can now include negative line items for credits and adjustments. Enhanced card schema in limits endpoint — Added cardholder_id, cardholder_name, created_at, and display_name fields to card data under the /limits endpoint. User access roles filter for limits — Added user_access_roles query parameter to the List Limits endpoint for role-based filtering. Minor unit conversion factor in currency response — Currency data now includes conversion factors for precise calculations. New entity relationship documentation — Comprehensive guide for understanding data connections across all Ramp objects. View guide Support for querying draft bills — Retrieve bills in draft status before they're finalized for payment processing. Filter archived bills — GET /bills endpoint now includes archived bills in response data. Filter transactions by spend program — Use spend_program_id parameter in GET /transactions to retrieve spend-program-specific transactions. Receipt affidavit URLs — GET /transactions now includes receipt affidavit URLs directly in the response for compliance workflows. Foreign exchange rates in bills — GET /bills now provides FX conversion rates for international payment processing. Vendor payment details management — Add and update vendor bank account information via POST /vendors/{vendor_id}/update-bank-accounts. View endpoint Filter purchase orders by spend request timeframe — Use spend_start_date and spend_end_date to retrieve POs tied to a specific spend window. New endpoint: POST /reimbursement/mileage — Log and submit mileage reimbursements via API. Search accounting vendors and GL accounts by remote_id — Simplifies mapping to ERP systems. Match bills to purchase orders — Enables programmatic linkage between bills and POs. Include is_manager in user invites — Supports setting manager status when inviting a user via API. Filter purchase orders by user_id — Use GET /purchase-orders with user_id to retrieve POs submitted by a specific user. accounting_date now returned in reimbursements — Available via GET /reimbursements for improved reconciliation workflows. New endpoint: POST /reimbursements/submit-receipt — Attach receipts directly to reimbursements via API. Auto-match uploaded receipts using OCR — POST /receipts can now automatically associate receipts with matching transactions. Temporary limit increases — Use PATCH /limits/{limit_id} to implement temporary spending limit boosts. Control declined transaction visibility — GET /transactions now defaults to excluding declines. Use state=DECLINED or state=ALL to include them. Search by accounting field selections — Filter transactions and bills based on assigned accounting fields for better categorization. Custom forms support — Retrieve and manage custom form metadata on Vendors, Purchase Orders, Transactions, and Limits using GET endpoints. API Updates New endpoint POST /connection//reactivate Support for specifying display_name on POST /accounting/fields New field card_present to GET /transactions Filter by employee_id for GET /transactions and GET /reimbursements Support for updating accounting custom field display_name New field accounting_date to GET /bills Support for requesting payment and tax details via email on POST /vendors Deprecated: GET /accounting/connection in favor of GET /accounting/all-connections Filter by awaiting_approval_by_user_id in GET /transactions and GET /reimbursements Support for creating vendors when approval policies are in place Filter bills by payee_id and sync_status parameters Support for managing vendor addresses via vendor APIs Ability to specify employee_id on user creation New fields status and last_linked_at to GET /accounting/connections New field transaction_accounting_date to transactions APIs Filter transactions by approval_status parameter Filter accounting custom field options by remote_code parameter Beta: Procurement API now available for Ramp Plus customers to manage Purchase Orders and Item Receipts for procurement workflows. Contact your Ramp representative for more information New sync_status field to Transactions, Reimbursements, Transfers, and Cashbacks for tracking sync state Filter with sync_status query parameter to retrieve records based on their sync state Query Accounting Custom Fields and Options by remote_id parameter for easier external system mapping Mark Accounting Custom Fields as required to enforce validation before sync-ready status Ramp MCP Server — Enables developers to expose business data through an LLM-friendly SQL interface. Available as a Python package with support for custom tools, data loaders, and SQL execution. View on GitHub or read our blog post Beta: Custom Records now available for Ramp Plus customers to add custom fields to users for advanced workflows (e.g., Cost Center, Division, Custom Approvers). Define and manage custom or native tables via CSV, SCIM, or API. Contact your Ramp representative for more information New endpoint GET /developer/v1/bank-accounts/{bank_account_id} to retrieve linked bank account information Bills and Vendors API Launch New: Manage vendors, bills, and payments via API for your Accounts Payable workflows All endpoints are accessible in both Sandbox and Production environments Support for creating, updating, deleting, and retrieving Vendors, Vendor Contacts, and Bills Deprecation Notice: Cards API Deprecated: Ramp is transitioning from the Cards API to the more flexible Limits API Use the Limits API for card issuance and management functionality The Limits API enables one-to-many relationships between limits and cards and shared limits across users Physical card shipping will continue to be supported via the Cards API until full migration support is provided --- title: Ramp CLI source_url: /developer-api/v1/cli text_url: /llms-guides/cli.txt summary: Authenticate with OAuth, manage expenses, approve bills, book travel, and more from your terminal or AI agent. content: Authenticate with OAuth, manage expenses, approve bills, book travel, and more from your terminal or AI agent. The CLI is open source. View the repo at github.com/ramp-public/ramp-cli. This detects your platform, downloads a pre-built binary, and sets up the ramp command. If you already have uv installed: The CLI uses OAuth to authenticate against the Ramp API. Run ramp auth login to open a browser-based OAuth flow. By default, the CLI connects to the Sandbox environment. Switch environments with the --env flag or set a default: Every CLI action runs as the user who authenticated via ramp auth login. This means: Actions are attributed to you. Approving a bill, submitting a reimbursement, or posting a comment will show your name in Ramp, just as if you performed the action in the dashboard. Permissions match your Ramp role. ramp transactions list --transactions_to_retrieve my_transactions returns your own transactions. all_transactions_across_entire_business requires admin access. If you can't see it in the dashboard, you can't see it in the CLI. Data visibility follows your access. Non-admins see only their own transactions, bills, and reimbursements. Admins can query across the business. Run ramp users me to confirm which user the CLI is acting as. The CLI supports two output modes. In a terminal, output defaults to human-readable tables. When piped, it switches to JSON automatically. --human Human-readable table output (default in terminal) --agent Machine-readable JSON output (default when piped) --wide Show all columns in table output The CLI includes a skill system for AI agent frameworks. Skills are structured instructions that teach an agent how to use Ramp for specific workflows like approving expenses, uploading receipts, or making purchases. Commands The CLI is organized into commands and resources. Commands handle setup and configuration. Resources map to API entities, each with their own set of tools. auth Login, logout, check status config Get/set CLI configuration env Show or set default environment (sandbox/production) applications Apply for a Ramp account skills Browse and install agent skill instructions feedback Submit feedback about the CLI 11 resources, each with their own tools. Usage: ramp [OPTIONS] accounting categories, category-options bills search, get, draft, pending, approve, attachments funds list, activate, creds, lock general comment, explain, help-center, policy purchase_orders search, get receipts upload, attach reimbursements list, pending, submit, approve, edit requests pending, approve transactions list, get, approve, edit, missing, flag-missing, explain-missing, memo-suggestions, trips travel list, create, bookings, locations users me, search, org-chart Run ramp --help to see all available flags for any tool. Global flags These flags work with any command: --env, -e sandbox (default) or production --output, -o Output format: json or table --quiet, -q Suppress progress output --no-input Disable interactive prompts (for CI/scripts) Each tool has its own flags. Common patterns: --json TEXT Raw JSON request body (bypasses flags) --dry_run, -n Print request without sending --page_size N Results per page --next_page_cursor Resume pagination from previous response Common workflows For non-interactive environments, use --no-input to disable prompts and --quiet to suppress progress output: To contribute to the CLI or run it from source: See the LICENSE for details. Need help? Submit a Developer API support ticket and our team will follow up. --- title: Custom Records source_url: /developer-api/v1/custom-records text_url: /llms-guides/custom-records.txt summary: The Custom Records API allows you to extend Ramp's data models with your own custom fields and data. Whether you need to add custom fields to existing Ramp objects or create entirely new data structures, this API provides the flexibility to integrate Ramp with your business processes. content: The Custom Records API allows you to extend Ramp's data models with your own custom fields and data. Whether you need to add custom fields to existing Ramp objects or create entirely new data structures, this API provides the flexibility to integrate Ramp with your business processes. Custom Records are available to Ramp Plus and Ramp Enterprise customers only. For more information, contact your Ramp representative. With the Custom Records API you can: Extend Native Objects: Add custom fields and relationships to Ramp objects such as Users, Locations, Departments, and Accounting Field Options Create Custom Tables: Build your own data structures to store business-specific information Link Data: Create relationships between custom and native data Query and Filter: Search and retrieve data using flexible filtering options At this time, the API supports writes to custom record values, as well as creating and reading table and column definitions. To get started, use the Custom Records Configuration API to set up tables and columns. Then, use the Native Tables and Custom Tables API to manage and manipulate data. Native Tables vs Custom Tables Custom Records track data in either Native Tables or Custom Tables, depending on the type of data. Native Tables allow extending core Ramp objects with custom fields These tables use Ramp IDs for row identification, matching rows to the core Ramp object they extend. See the Supported Native Tables section for a list of supported native tables and how to reference them. If a Ramp ID is provided that does not yet exist for a table, the row will not be created and an error will be returned. If a referenced native Ramp object is deleted, the extension row will not be accessible. Queries and references will indicate value not found. If additional extensibility above what a Ramp object provides is required, Custom Tables can be used. Custom Tables can store arbitrary data, and can help represent data that doesn't fit into the core Ramp objects. Rows that are on Custom Tables are identified using external keys. If an external_key field is provided that does not yet exist for a table, a new row with that external_key will be created. Note that external keys are immutable, case-sensitive, and must be unique within a table. This diagram shows: Users (Native Table) Has one home_state (reference to the States table) Can be a Regional Director for one or more regions (column corresponding to the regional_directors column on the Regions table) Uses Ramp User UUID as primary key Has one home_state (reference to the States table) Can be a Regional Director for one or more regions (column corresponding to the regional_directors column on the Regions table) Uses Ramp User UUID as primary key States (Custom Table) Has one region (reference to the Region table) Has many Users (column corresponding to the home_state column on the Users table) Uses external_key as primary key Has one region (reference to the Region table) Has many Users (column corresponding to the home_state column on the Users table) Uses external_key as primary key Regions (Custom Table) Can have many Regional Directors (reference to the User table) Has many States (column corresponding to the region column on the States table) Uses external_key as primary key Can have many Regional Directors (reference to the User table) Has many States (column corresponding to the region column on the States table) Note how bidirectional relationships are maintained automatically through corresponding columns. The example matches the schema shown in the diagram above, showing how Users can have a home state and be regional directors for multiple regions. Creating Tables To add custom fields to existing Ramp objects, you need to first extend the native table. This creates a container for your custom columns on that native object: For a list of supported Ramp tables, see the Supported Native Tables section. Extending the Users table: Custom tables allow you to store arbitrary business data that doesn't fit into Ramp's core objects. To create a custom table, use the /configure/custom-tables endpoint: Let's create the States and Regions tables from our example: Creating the States table: Creating the Regions table: Note: The name (or API name), is used to identify the table across API calls. It must be a lowercase, alpha-only slug. Underscores are permitted, but not at the beginning and end. The table label is displayed to users within Ramp and can be an arbitrary string. Creating Columns Once you've created or extended a table, you can add columns to store data. There are two types of columns: reference columns for relationships between tables, and primitive columns for simple values. When creating custom columns, you will need to specify a name (also called an API name) and column label. The API name is used to identify the column across API calls while the column label is displayed to users within Ramp. They have the same value constraints as table API names and labels. Reference columns create relationships between tables. When you create a reference, the API automatically creates a corresponding column on the referenced table to maintain bidirectional relationships. For more information, see the Bidirectional References and has_more section. Adding a home_state column to the Users native table: This creates: A home_state column on Users that references States (many Users can have one State) A residents column on States that shows all Users from that state (automatically maintained) Adding a region column to the States table: Adding regional_directors to the Regions table: Primitive columns store simple data types like text or boolean values, useful for storing properties of an object, like a State's Name. To create a column, use the /columns endpoint for your table: Adding a name column to the States table: Note: Primitive columns are typically less useful in workflows, as it's harder to make conditions based on them. If you would like to create workflow conditions that check for a specific value of a column, you should make a Custom Table and use a reference column instead. Working with Tables To get started with either custom or native tables: List available tables using the /custom-tables or /native-tables endpoints Get column definitions for a specific table using the /{table_name}/columns endpoint Use the column information to understand the table's structure and available fields Primitive columns A text column contains simple text/string values A boolean column contains true or false values Reference columns Reference columns are a special type of column that can reference rows on other tables. They can either be: A native_reference to a Native Table, linking to core Ramp objects (users, departments, locations, etc.) When writing a reference value, requires both Ramp column_name and Ramp object value for identification (e.g., {"column_name": "id", "value": ""}) When writing a reference value, requires both Ramp column_name and Ramp object value for identification (e.g., {"column_name": "id", "value": ""}) A custom_reference to a Custom Table, linking to other custom tables you've created Only requires the external key for identification Only requires the external key for identification For custom tables, you can: Create or update rows using PUT /custom-tables/{table_name}/rows Delete rows using DELETE /custom-tables/{table_name}/rows Append or remove individual cells using the -/append and -/remove endpoints For native tables, you can: Read rows using GET /native-tables/{table_name}/rows Update custom field values using PUT /native-tables/{table_name}/rows Append or remove custom field values using the -/append and -/remove endpoints When writing to rows, keep these important points in mind: All rows in a single PUT request must write to the same set of columns. If a row should not have a value for a column, that column must still be included in the request with an explicit null contents value. If a row should not have a value for a column, that column must still be included in the request with an explicit null contents value. For columns that reference multiple items, each reference must be a separate cell entry References to custom tables require only the external key, while references to native tables require both a column name and value Some columns (those with allows_writes=False) do not allow direct writes. In these cases, write to the corresponding, writable column on the other table instead. For more information, see the Bidirectional References and has_more section. PUT operations on columns that reference multiple items (lists) will replace all existing values with the provided values. To modify list contents without replacing everything, use the -/append and -/remove endpoints A PUT operation with a null contents value will remove all values from that field For best performance: Write to one reference column at a time when updating multiple references Or write to multiple columns at once when setting single values Write to one reference column at a time when updating multiple references Or write to multiple columns at once when setting single values Using the example Custom Table schema for Regions from above, let's setup the Northeast region to have one regional director (User email=alice@company.com) and Southwest region to have two regional directors (User id=01956422-6793-7700-adb4-3f1bd635ee49, User email=bob@company.com). Note how: The Northeast region has a single director, referenced by email The Southwest region has two directors, one referenced by UUID and one by email Each director reference is a separate cell entry All references to native tables (Users) include both column_name and value For more information about referencing native tables, including supported column names for identification, see the Supported Native Tables section. Pagination and Filtering When listing rows, both custom and native tables support: Page size control (default: 50, max: 100) Cursor-based pagination using the start parameter Filtering by external keys (custom tables) or Ramp IDs (native tables) Column-specific filters using filter.column_name.operation You can filter table rows by specific column values using the format filter.column_name.operation=value. The following operations are supported: one_of: Match any value in a list is_not: Matches no values in a list For columns that reference other tables, use different identifiers based on the table type: Native tables: Use the Ramp ID as the filter value Custom tables: Use the external key as the filter value Example filters: Example query for a information about a specific Ramp user: This response shows: The user's home state (California) The regions they are a director for (West and Northwest) Both relationships are maintained automatically through bidirectional references has_more: false indicates we have all the references for each relationship When you create a reference between tables, the API automatically maintains the reverse relationship by creating a corresponding column: Reference Column: The column you create (e.g., home_state on Users) Corresponding Column: Automatically created on the referenced table (e.g., residents on States) Key points about corresponding columns: The corresponding_column_name is required when creating a reference The corresponding_column_label is optional and will be auto-generated if not provided Corresponding columns have allows_writes=false - you must write to the original reference column This bidirectional relationship allows you to: Navigate data relationships in both directions Maintain data consistency Build complex queries from any starting point When a reference column's contents have has_more as true, it indicates that not all referenced rows are included in the response. To retrieve the complete set of references, you'll need to query the referenced table directly using the corresponding column. To get all states in the West region, query the states table using the corresponding column: This will return all states with the a reference to the West Region in their region column. Supported Native Tables Note that when provding a contents value that references a ramp object, it should be formatted similarly to: {"column_name": "id", "value": }. Different Native Ramp tables allow other column names to be used as well. id User's Ramp UUID {"column_name": "id", "value": ""} email User's email address {"column_name": "email", "value": "user_email@company.com"} Users endpoint Location's Ramp UUID {"column_name": "id", "value": ""} name Location's name {"column_name": "name", "value": "New York City"} Locations endpoint Department's Ramp UUID {"column_name": "id", "value": ""} Department's name {"column_name": "name", "value": "Engineering"} Departments endpoint Option's Ramp UUID {"column_name": "id", "value": ""} field_id::option_id Combined accounting field remote id and accounting field option remote id {"column_name": "field_id::option_id", "value": "Projects::Project A"} Make sure that if you're using this format, Accounting Field Options endpoint Note: Use the ramp_id from the response to reference the accounting field option in a custom table or row. Entity's Ramp ID {"column_name": "id", "value": ""} Enitity's name {"column_name": "name", "value": "Acme Corp LLC"} Entities Endpoint Bill's Ramp UUID {"column_name": "id", "value": ""} Bills endpoint Transaction's Ramp UUID {"column_name": "id", "value": ""} Transactions endpoint Reimbursement's Ramp UUID {"column_name": "id", "value": ""} Reimbursements endpoint --- title: Data Relationships source_url: /developer-api/v1/data-relationships text_url: /llms-guides/data-relationships.txt summary: Relationship information is automatically shown in each resource's documentation. Look for relationship indicators next to UUID fields that reference other resources. content: Relationship information is automatically shown in each resource's documentation. Look for relationship indicators next to UUID fields that reference other resources. Ramp's API resources are interconnected through a rich set of relationships that mirror real-world business processes. Understanding these relationships is crucial for building effective integrations, especially when you need to: Plan complex integrations that span multiple resources Optimize API calls by understanding data dependencies Build comprehensive reporting that connects related data Design user interfaces that reflect business workflows When viewing any API resource, you'll see interactive relationship indicators next to UUID fields that reference other resources. These indicators show the target resource and relationship type, with clickable links for easy navigation. Relationship Types The most common relationship type where multiple records reference a single parent record. Examples: Users → Department: Many employees belong to one department Transactions → User: Many transactions are made by one cardholder Bills → Vendor: Many bills are paid to one vendor A single parent record has multiple child records. Department → Users: One department has many employees Vendor → Bills: One vendor receives multiple bills User → Cards: One user can have multiple cards A direct relationship between two specific records. Business → Primary Location: Each business has one primary location Card → Primary User: Each card has one primary cardholder --- title: Debugging source_url: /developer-api/v1/debugging text_url: /llms-guides/debugging.txt summary: Ramp APIs will return an x-trace-id header in all API responses. The x-trace-id is particularly helpful for debugging, as it enables correlation between logs, metrics, and the API response, providing greater visibility into how the request was processed. content: Ramp APIs will return an x-trace-id header in all API responses. The x-trace-id is particularly helpful for debugging, as it enables correlation between logs, metrics, and the API response, providing greater visibility into how the request was processed. Include the x-trace-id when reaching out to Ramp support for quicker issue resolution. Use the x-trace-id to track specific requests across different systems and identify potential bottlenecks or failures. Make sure to log the x-trace-id in your application for easy reference in case you need to troubleshoot any API interactions. Every API response includes the trace ID in the headers: When contacting support, always include this trace ID for faster resolution. How to Submit a Developer API Support Ticket 1. Navigate to Company > Developer In the left-hand navigation, click Company to expand the menu, then select Developer. (You can skip this step if you're accessing directly from the developer console.) 2. Open Developer API Support On the Developer page, click the Developer API Support card. 3. Select "Connect to Developer Support team" In the chat window, select Connect to Developer Support team. 4. Answer the agent's questions The AI assistant will ask you a few questions about your issue. Answer as completely as you can, then review the pre-filled support ticket form to confirm the details look accurate. 5. Click "Submit Ticket" Click Submit Ticket to send your request to the team. Our Developer Support team will follow up with you over email. --- title: Deferred Tasks source_url: /developer-api/v1/deferred-tasks text_url: /llms-guides/deferred-tasks.txt summary: Some API calls, for example requesting for a new card, require asynchronous processing. They are all denoted with /deferred/ in the request URL. content: Some API calls, for example requesting for a new card, require asynchronous processing. They are all denoted with /deferred/ in the request URL. For these tasks, the API will return immediately with a task ID. This ID can then be used to call a GET deferred/status/{id} endpoint to check the status of the corresponding task. For example, let's create a new virtual card. The initial request to POST /developer/v1/cards/deferred/virtual will return an ID. This means that asynchronous task processing has started. Information about the task can be requested by calling the relevant deferred task status endpoint, in this case by calling GET /developer/v1/card/deferred/status/eca553b8-6923-42b2-aea9-8f3c15b079ff. The following information is made available: status: Represented by one of the following - STARTED, IN_PROGRESS, ERROR, SUCCESS. data: Additional details on status. If the task processing succeeded, status="SUCCESS"; in the case of creation tasks, the id field returns the new object ID. If the task processing failed, as indicated by status="ERROR", the error field is populated with information about the error. context: Static information about the initial request such as acting_user_id. For tasks with existing objects, such as card suspension, the ID of the targeted Ramp object is available. You should poll the status endpoint periodically until the task completes: Once the status becomes SUCCESS or ERROR, the task is complete and you can proceed accordingly. --- title: Developer MCP source_url: /developer-api/v1/developer-mcp text_url: /llms-guides/developer-mcp.txt summary: The Developer MCP server is subject to change. Feedback and questions can be submitted via a Developer API support ticket. content: The Developer MCP server is subject to change. Feedback and questions can be submitted via a Developer API support ticket. Developer MCP is Ramp's specialized Model Context Protocol server designed for developers building with Ramp's API. It enables AI assistants to provide real-time API help, lookup schemas, and offer implementation guidance directly within your development workflow. Unlike other Ramp MCP servers, no Ramp account is needed — making it accessible to any developer exploring or integrating with Ramp's API. Why Use Developer MCP? Get immediate answers to API questions without switching contexts or searching through documentation. Ask natural language questions about authentication, endpoints, schemas, and implementation patterns. Retrieve up-to-date OpenAPI schemas and get suggestions for related endpoints as you build, ensuring your integration stays current with Ramp's API. Reduce time spent on API documentation searches and common implementation questions, letting you focus on building your integration. Getting Started Server URL: https://mcp.ramp.com/developer/mcp Open Claude Desktop Navigate to Settings → Developer Click 'Edit config' Add the Developer MCP server: Restart Claude Desktop — Developer MCP works instantly without any authentication Add the Developer MCP server to your Claude Code session: Then run /mcp in your Claude Code session to activate the server and start asking API questions. Cursor Desktop App Required The Cursor desktop app must be installed for this one-click link to work. For clients supporting remote MCP connections, use the server URL: https://mcp.ramp.com/developer/mcp Refer to your client's MCP documentation for specific configuration steps. Available Tools The Developer MCP provides three core tools for API assistance: Intelligent documentation search with intent detection Search Ramp's API documentation using natural language queries Get contextual results based on your specific question or use case Returns relevant endpoints, examples, and implementation guidance Real-time OpenAPI schema retrieval with related endpoint suggestions Get the complete OpenAPI schema for any Ramp API endpoint Receive suggestions for related endpoints that might be useful Ensures you're working with the most current API specifications Direct feedback channel to Ramp's developer experience team Report issues, suggest improvements, or share feedback about the API or MCP server Helps us continuously improve the developer experience Troubleshooting Configuration not working: Verify JSON syntax in configuration files Ensure file paths are correct for your operating system Restart your client after making configuration changes Node.js or npm issues: Ensure Node.js is properly installed Try npm install -g mcp-remote to install the required package Remote MCP connection issues: Remote MCP connections are early technology. If connection fails, restart your client and try again Ensure your client supports HTTP-based MCP connections Support: Submit a Developer API support ticket Feedback Tool: Use the submit_feedback tool directly within the MCP interface --- title: Errors source_url: /developer-api/v1/error-handling text_url: /llms-guides/error-handling.txt summary: The Ramp API returns detailed error information in the response body along with standard HTTP status codes. This allows you to quickly diagnose and address issues with your API requests. content: The Ramp API returns detailed error information in the response body along with standard HTTP status codes. This allows you to quickly diagnose and address issues with your API requests. Here is an example of an error response: The Ramp API ignores extra request parameters or body fields that are not defined in the endpoint specification. This means: Sending additional query parameters that aren't documented won't cause an error Including extra fields in the request body won't cause validation failures Your requests will succeed as long as all required fields are present and valid This behavior allows for forward compatibility but means you won't receive warnings about misspelled field names or deprecated parameters. We recommend validating your requests against the schema documentation during development. Inspect HTTP Status Codes: Use status codes to identify the category of the error (e.g., 4xx for client errors, 5xx for server errors). Inspect HTTP Status Codes: Use status codes to identify the category of the error (e.g., 4xx for client errors, 5xx for server errors). Utilize the error_v2 Field: Parse the error_code and additional_info to pinpoint the issue and provide actionable feedback in your application. Utilize the error_v2 Field: Parse the error_code and additional_info to pinpoint the issue and provide actionable feedback in your application. Log Errors: Log error responses, including the x-trace-id from the response headers, for easier debugging and communication with Ramp developer support. Log Errors: Log error responses, including the x-trace-id from the response headers, for easier debugging and communication with Ramp developer support. Implement Retry Logic: For transient errors (e.g., 429 Too Many Requests or 5xx), implement exponential backoff to retry requests. Implement Retry Logic: For transient errors (e.g., 429 Too Many Requests or 5xx), implement exponential backoff to retry requests. Provide User Feedback: Use the message field to display clear and concise error messages to users, when applicable. Provide User Feedback: Use the message field to display clear and concise error messages to users, when applicable. 400 Bad Request - Invalid request format 401 Unauthorized - Invalid or missing API token 403 Forbidden - Insufficient permissions 404 Not Found - Resource doesn't exist 422 Unprocessable Entity - Validation errors 429 Too Many Requests - Rate limit exceeded 500 Internal Server Error - Server-side issue 504 Gateway Timeout - Request exceeded the 60-second timeout --- title: Getting Started source_url: /developer-api/v1/getting-started text_url: /llms-guides/getting-started.txt summary: This guide will help you make your first Ramp API call in just a few minutes. You'll create an access token and call the Transactions API to retrieve transaction data. content: This guide will help you make your first Ramp API call in just a few minutes. You'll create an access token and call the Transactions API to retrieve transaction data. This guide assumes you are a Ramp customer with admin access to your dashboard. Need a test environment for development? Request access to our Sandbox. First, you'll need to create a developer app to get your API credentials. In your Ramp account, go to Company → Developer (you'll need admin access). Click Create New App. Name your app (e.g., "API Quickstart") and accept the Terms. Under Grant types, click Add new grant type → select Client Credentials. Under Scopes, click Configure allowed scopes and select transactions:read. Copy your Client ID and Client Secret. Store them securely – you'll need them in the next step. For more details on authorization, see the Authorization Guide. With your credentials, request an access token. The token authenticates your API requests. Replace {environment-url} with: https://demo-api.ramp.com for Sandbox https://api.ramp.com for Production Response: Copy the access_token – you'll use it to make API calls. Tokens expire after 10 days. With your access token, you can now call the Ramp API. Let's retrieve your transactions using the GET /transactions endpoint. Add the header Authorization: Bearer and make a GET request to {environment-url}/developer/v1/transactions. --- title: Introduction source_url: /developer-api/v1/introduction text_url: /llms-guides/introduction.txt summary: Automate spend, connect your systems, and build powerful integrations—all with one API. content: Automate spend, connect your systems, and build powerful integrations—all with one API. Learn more about building integrations with Ramp. Start Building View documentation View OpenAPI Spec Quickstart Guides Make your first API call in minutes Authorize with OAuth 2.0 for secure access Manage team spending with cards and funds Optimize payments with Virtual Cards Connect your ERP or accounting system Use the Ramp MCP to chat with your data Manage Ramp from the terminal with the CLI Need help? Submit a Developer API support ticket and our team will follow up. --- title: MCP source_url: /developer-api/v1/mcp text_url: /llms-guides/mcp.txt summary: The Model Context Protocol (MCP) enables AI assistants to securely connect to your business data and systems. Instead of copying and pasting information or switching between applications, you can ask your AI assistant direct questions about your Ramp account and get instant, accurate answers. content: The Model Context Protocol (MCP) enables AI assistants to securely connect to your business data and systems. Instead of copying and pasting information or switching between applications, you can ask your AI assistant direct questions about your Ramp account and get instant, accurate answers. MCP Options --- title: Monetary Values source_url: /developer-api/v1/monetary-values text_url: /llms-guides/monetary-values.txt summary: In the Ramp API, monetary values are represented by the currency_code and amount. All currency_code values are three-letter acronyms as defined in ISO 4217 (e.g., USD for US Dollars). There are two representations of the amount: content: In the Ramp API, monetary values are represented by the currency_code and amount. All currency_code values are three-letter acronyms as defined in ISO 4217 (e.g., USD for US Dollars). There are two representations of the amount: Canonical representation (Preferred) Ramp's preferred method for representing monetary values is canonical representation, which uses the CurrencyAmount type to group amount and currency_code together. The amount is represented as an integer in the smallest denomination to avoid precision loss. For example: USD: $40 is represented as 4000 (since 1 USD = 100 cents) JPY: ¥5000 is represented as 5000 (since 1 JPY = 1 yen) To calculate the correct amount for different currencies, the canonical representation multiplies the amount by 10 raised to the power of D, where D is the number of decimal places for the currency. You can find the D value for any currency in the ISO 4217 Wikipedia page. USD, EUR, GBP, etc.: D = 2 (i.e., multiply the amount by 100 for cents) JPY: D = 0 (i.e., no decimal places) Formula: For example, for USD: USD 4000 ($40.00) 2 EUR 10000 (€100.00) JPY 5000 (¥5000) 0 GBP 2500 (£25.00) Below is the schema definition of CurrencyAmount type: The legacy representation is an older way of representing amounts. Although this method is still supported for backward compatibility, it is deprecated and will be replaced in future releases. You should migrate to the canonical representation for new development. Date and DateTime are represented using a string that conforms to ISO8601; UTC is assumed if no timezone offset is specified. For example, --- title: Pagination source_url: /developer-api/v1/pagination text_url: /llms-guides/pagination.txt summary: Pagination allows you to retrieve an entire dataset with a series of requests, where each request fetches a portion of the data set. By loading data in smaller chunks, pagination reduces the amount of data transmitted per response and alleviates the load on the servers, ensuring faster loading times and a smoother user experience. content: Pagination allows you to retrieve an entire dataset with a series of requests, where each request fetches a portion of the data set. By loading data in smaller chunks, pagination reduces the amount of data transmitted per response and alleviates the load on the servers, ensuring faster loading times and a smoother user experience. Ramp API uses a mechanism called keyset pagination to divide data into fixed-size pages. Keyset pagination relies on the use of one or more columns with unique, ordered values in the database table. These columns are typically indexed for fast retrieval. How Keyset Pagination Works Here's how keyset pagination works step-by-step: To start, initiate a request for the first page of results. The API response will include a next field, which contains the complete URL for accessing the next page of data. Utilize the URL provided in the next field to send a subsequent request for the next page of results. To construct the query for fetching this subsequent set of records, the client incorporates the start query parameter as a cursor. Repeat the process of requesting subsequent pages using the next URL and updating the start cursor parameter until the API returns a null value for the next field. This indicates that all records have been successfully fetched. --- title: Ramp MCP source_url: /developer-api/v1/ramp-mcp text_url: /llms-guides/ramp-mcp.txt summary: Ramp MCP is subject to change. Feedback and questions can be submitted via a Developer API support ticket. content: Ramp MCP is subject to change. Feedback and questions can be submitted via a Developer API support ticket. Ramp MCP allows you to securely connect Ramp with AI assistants like ChatGPT and Claude, so you can query Ramp data and take actions with natural language. Admins can analyze data to identify spend trends and forecasting insights, while employees can check balances, request reimbursements, or get policy answers directly from their daily tools. Example Use Cases Getting Started A Ramp production or sandbox account Access to your chosen AI platform (Claude, ChatGPT, etc.) Using demo data Replace https://mcp.ramp.com/mcp with https://demo-mcp.ramp.com/mcp in any config below to use sample data instead of live Ramp data. Add the Ramp MCP server to your Claude Code session: Run /mcp in your session to verify the connection. Cursor desktop app required The Cursor desktop app must be installed for this one-click link to work. Or add manually to ~/.cursor/mcp.json: Add the following to your Claude Desktop config file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Add the following to your VS Code MCP settings: For any MCP-compatible client, use the server URL to configure a connection: Production: https://mcp.ramp.com/mcp Demo: https://demo-mcp.ramp.com/mcp Check your tool's MCP documentation for configuration format. After setup, try a prompt to confirm everything is working: "What Ramp cards do I have?" "Show me my recent transactions" In Claude Code, run /mcp to check that the Ramp server appears in your connected servers list. Admins can control which employees have access to Ramp MCP through Integrations: Navigate to Company → Integrations → Ramp MCP in your Ramp dashboard Select 'Manage Access' Set restrictions based on roles, departments, or specific users This provides fine-grained control over who can use AI copilots to access Ramp data and functionality. Employee Tools: Available to all Ramp users, but respect individual user permissions (e.g., users will only see funds and cards available to their account) Admin Tools: Only available to users with admin or business owner permissions Agent card tools are in beta ramp_get_agent_card_creds and ramp_get_agent_card_funds are currently in beta. Users can join the waitlist at agents.ramp.com/cards. ramp_activate_card Activate a physical Ramp card ✅ ramp_answer_policy_question Answer natural-language questions about company policies ramp_approve_or_reject_bill Approve or reject a bill ramp_approve_or_reject_reimbursement Approve or reject a reimbursement ramp_approve_or_reject_request Approve or reject a request ramp_approve_or_reject_transaction Approve or reject a transaction ramp_ask_help_center Answer questions using Ramp Help Center content ramp_create_trip Create a trip in Ramp Travel ramp_edit_reimbursement Edit a reimbursement's details before submission ramp_edit_transaction Edit transaction details such as coding or notes ramp_get_agent_card_creds Get agent card credentials for users with approved beta access ramp_get_agent_card_funds Get agent card funding details for users with approved beta access ramp_get_bill_details Get detailed information for a specific bill ramp_get_bill_invoices Retrieve invoice files and metadata for a specific bill ramp_get_bills_for_approval List bills awaiting the current user's review ramp_get_bookings Retrieve travel bookings for the current user ramp_get_candidate_trips_for_transaction Find matching trips for a transaction ramp_get_decline_explanation Explain why a transaction or request was declined ramp_get_draft_bill_details Get detailed information for a draft bill ramp_get_flight_booking_locations Resolve free-text flight locations into standardized airport data ramp_get_full_transaction_metadata Retrieve full metadata for a specific transaction ramp_get_funds List all funds, stipends, or budgets available to the current user ramp_get_org_chart Get the org chart around a user ramp_get_purchase_order_details Get detailed information for a specific purchase order ramp_get_reimbursements Get reimbursements for the current user ramp_get_reimbursements_for_approval List reimbursements awaiting the current user's review ramp_get_requests_to_review List requests awaiting the current user's review ramp_get_simplified_user_detail Get the current user's basic Ramp profile and permissions context ramp_get_tracking_categories List available tracking categories ramp_get_tracking_category_options List options for a tracking category ramp_get_transaction_missing_items Check what required items are missing for a transaction ramp_get_transaction_suggested_memos Get AI-suggested memo options for a transaction ramp_get_transactions Get transaction history for the current user ramp_get_user_trips Retrieve trips for a user ramp_list_cards List all Ramp cards available to the current user ramp_lock_or_unlock_card Lock or unlock a specific Ramp card by card ID ramp_mark_transaction_missing_receipt Mark a transaction as missing a receipt ramp_post_comment Post a comment on a supported Ramp workflow item ramp_provide_no_receipt_reason Record a no-receipt explanation for a transaction ramp_search_bills Search bills the current user can access ramp_search_purchase_orders Search purchase orders the current user can access ramp_search_user Search for users in the Ramp account ramp_submit_reimbursement Submit a reimbursement execute_query Run SQL queries on loaded data ❌ clear_table Clear specific tables from memory load_spend_export Load transactions, reimbursements, and bills (recommended) load_purchase_orders Load purchase order data load_cards Load card information load_limits Load spending limit data load_entities Load entity information load_departments Load department data load_users Load user/employee data load_memos Load memo data load_locations Load office location data load_spend_programs Load spend program data load_vendors Load vendor information get_ramp_categories Get all available Ramp spending categories Troubleshooting Authentication fails or connection drops: Claude Code: Run /mcp, select Ramp, and choose "Clear authentication" Cursor / Claude Desktop: Remove and re-add the server in your config, then restart the app ChatGPT: Disconnect and reconnect the Ramp app in Settings → Apps Clear cached MCP auth: rm -rf ~/.mcp-auth (if applicable) Ensure you're logged into the correct Ramp account "ETL operation limit reached": Wait for current data operations to complete Ask the AI to clear unused tables to free up resources "Query returned more than 100 rows": The AI will automatically add more specific filters and retry All questions and feedback about Ramp MCP can be submitted via a Developer API support ticket --- title: Rate Limiting and Timeouts source_url: /developer-api/v1/rate-limiting text_url: /llms-guides/rate-limiting.txt summary: API requests that take longer than 60 seconds will be terminated and return a 504 Gateway Timeout response. Most API requests complete well within this limit, but if you're working with large datasets or complex queries: content: API requests that take longer than 60 seconds will be terminated and return a 504 Gateway Timeout response. Most API requests complete well within this limit, but if you're working with large datasets or complex queries: Use pagination to break large requests into smaller chunks. Implement retry logic with exponential backoff for any 504 responses. To ensure reliable and equitable access to our API, we enforce rate limiting. By default, API requests are limited as follows, applied per source IP address: Limit: 200 requests per 10-second rolling window. Reset Mechanism: The window operates on a rolling basis, meaning every new request resets the 10-second timer for that particular request. When the rate limit is exceeded, the API responds with a 429 Too Many Requests status code. This indicates that further requests should be paused until the limit resets. Implement Backoff Strategies: When receiving a 429 Too Many Requests response: Implement exponential backoff (e.g., 1s, 2s, 4s) before retrying. Avoid immediate retries, as this could worsen delays. Implement exponential backoff (e.g., 1s, 2s, 4s) before retrying. Avoid immediate retries, as this could worsen delays. Optimize API Calls: Consolidate requests wherever possible, such as using batch endpoints or minimizing redundant calls. If you make 200 requests at 10:00:00, the limit will be reached, and subsequent requests will return a 429 response. If no further requests are made, the limit will reset by 10:00:10. However, if you continue making requests during the window, the rolling timer will extend accordingly. If your application requires a higher limit, you can request an increase. To do so: Analyze and document your expected API usage. Submit a Developer API support ticket with your account details and usage requirements. Providing clear information about your use case and anticipated volume will help expedite the review process. --- title: Sandbox source_url: /developer-api/v1/sandbox text_url: /llms-guides/sandbox.txt summary: The Ramp sandbox is a testing environment where developers and partners can safely build, test, and experiment with Ramp's API without affecting live production data. content: The Ramp sandbox is a testing environment where developers and partners can safely build, test, and experiment with Ramp's API without affecting live production data. Key features: Safe testing environment: Test integrations and applications before deploying to production API development: Access Ramp's Developer API for building custom integrations No real money movement: Demo accounts cannot process actual financial transactions How to get sandbox access Developers/Partners: Submit a request through the Ramp technology partnerships page to receive both sandbox and developer console access Existing customers: Request a sales sandbox through your Account Manager Ramp frontend https://demo.ramp.com Access the Ramp user interface for testing API https://demo-api.ramp.com Base URL for API calls in the Sandbox environment Test demo actions While building with the dev API, we support simulation actions to support testing within the Ramp sandbox environment. You can simulate user events through the demo actions panel. You can open the demo actions panel directly within the Ramp sandbox with ⌘ J. To mark a bill as paid, navigate to Bill Pay via the UX, then open the bill you want to mark as paid. Press ⌘ J to open the demo actions panel and select 'pay current bill'. Note: This demo action depends on your Bill Pay payment release setting. When enabled, it only works for bills that are approved and scheduled. When disabled, it works for all bills. For more information, see Bill Pay payment release documentation. To mark a reimbursement as paid, navigate to the reimbursements tab and select "needs review" to find pending reimbursements. Open the reimbursement you want to mark as paid, then press ⌘ J to open the demo actions panel and select "Mark reimbursement as paid". To create a transaction, you can do this from any page within the sandbox environment. Press ⌘ J to open the demo actions panel and click on "add transactions". Each demo action requires specific permissions to work properly: Admin or Business Owner role, or the AP Clerk permission Mark reimbursement as approved The direct manager of the employee who submitted the reimbursement (or a manager in their reporting chain), Admin, or Bookkeeper role Employee role or higher (Manager, Admin, or Bookkeeper). The Employee role allows users to request spend, receive cards, make purchases, and submit reimbursements. View-only Admins and Guests cannot create transactions. --- title: Sync Button source_url: /developer-api/v1/sync-button text_url: /llms-guides/sync-button.txt summary: This guide explains how integrators can set up the Accounting Sync Button for Accounting API-based connections. Once enabled for your integration, connected customers can initiate transaction and reimbursement syncs directly from the Ramp UI. content: This guide explains how integrators can set up the Accounting Sync Button for Accounting API-based connections. Once enabled for your integration, connected customers can initiate transaction and reimbursement syncs directly from the Ramp UI. Note: This feature is currently in Alpha. Transaction Sync Button appears on Accounting > Transactions and requires transactions:read, accounting:read, and accounting:write Reimbursement Sync Button appears on Accounting > Reimbursements and requires reimbursements:read, accounting:read, and accounting:write Both flows use the same accounting connection pattern: subscribe to a webhook, enable the sync button on the connection, fetch items with the requested_to_sync filter, then POST the sync result back to /developer/v1/accounting/syncs Transaction Sync Button Create a webhook subscription with the transactions.sync_requested event type. This will fire when the sync button is pressed. To create the webhook, make a POST call to the /developer/v1/webhooks endpoint and include transactions.sync_requested in the event_types array: Ramp will send a POST request with a challenge to your endpoint during setup: Receive the challenge string from Ramp Respond by making a verification API call: Enable the setting that allows the transaction sync button for this connection. Once turned on, this shows the Sync button on the Accounting > Transactions page in Ramp. Note This setting is managed at the Accounting Connection level. If you plan on creating multiple Accounting Connections, you need to configure this setting for each connection. For new connections: Make a POST call to /developer/v1/accounting/connection with settings.transaction_sync_button_enabled set to true: For existing connections: First, retrieve your connection ID by making a GET call to /developer/v1/accounting/connection: Then make a PATCH call to /developer/v1/accounting/connection/{connection_id}, using the id from the previous response as the connection_id, with settings.transaction_sync_button_enabled set to true: Once enabled, the Sync button appears on the Accounting > Transactions page in Ramp. Since you've subscribed to the webhook, you will receive a transactions.sync_requested event when a customer clicks the Sync button: For the remaining steps, keep track of the sync_request_id value. Important: 5-minute response window You must respond by posting the Accounting Sync within 5 minutes of receiving the webhook. Transactions that don't have a sync posted within that window will be automatically marked as failed. After receiving the transactions.sync_requested webhook, fetch the transactions that were requested for sync by calling the /developer/v1/transactions endpoint with the requested_to_sync filter. Only the transactions that were requested to sync will be returned. Once you've synced the transaction data to your system, make a POST call to /developer/v1/accounting/syncs. Include the sync_request_id from the webhook payload in the request body. Notes: You can make multiple API calls to POST /developer/v1/accounting/syncs per sync request by providing the same sync_request_id. Ramp will update the UI in real time with the accurate number of transactions successfully synced or failed. Customers will see the same sync flow in the UI as they would with a direct Ramp accounting integration: Click the Sync All button in the top right of the screen, or select specific transactions to sync individually. View the sync progress at the top of the screen in real time. See a summary of successes and errors (with error reasons) in the UI once the sync completes. Reimbursement Sync Button Create a webhook subscription with the reimbursements.sync_requested event type. This will fire when the sync button is pressed. To create the webhook, make a POST call to the /developer/v1/webhooks endpoint and include reimbursements.sync_requested in the event_types array: Enable the setting that allows the reimbursement sync button for this connection. Once turned on, this shows the Sync button on the Accounting > Reimbursements page in Ramp. For new connections: Make a POST call to /developer/v1/accounting/connection with settings.reimbursement_sync_button_enabled set to true: Then make a PATCH call to /developer/v1/accounting/connection/{connection_id}, using the id from the previous response as the connection_id, with settings.reimbursement_sync_button_enabled set to true: Once enabled, the Sync button appears on the Accounting > Reimbursements page in Ramp. Since you've subscribed to the webhook, you will receive a reimbursements.sync_requested event when a customer clicks the Sync button: You must respond by posting the Accounting Sync within 5 minutes of receiving the webhook. Reimbursements that don't have a sync posted within that window will be automatically marked as failed. After receiving the reimbursements.sync_requested webhook, fetch the reimbursements that were requested for sync by calling the /developer/v1/reimbursements endpoint with the requested_to_sync filter. Only the reimbursements that were requested to sync will be returned. Once you've synced the reimbursement data to your system, make a POST call to /developer/v1/accounting/syncs. Include the sync_request_id from the webhook payload in the request body. Ramp will update the UI in real time with the accurate number of reimbursements successfully synced or failed. Click the Sync All button in the top right of the screen, or select specific reimbursements to sync individually. --- title: Tax Codes source_url: /developer-api/v1/tax-codes text_url: /llms-guides/tax-codes.txt summary: Tax code endpoints are currently in Beta. During the beta, endpoints may be subject to breaking changes, which will be announced via the Changelog. content: Tax code endpoints are currently in Beta. During the beta, endpoints may be subject to breaking changes, which will be announced via the Changelog. Tax codes allow you to associate tax rates with transactions in Ramp, keeping your ERP and Ramp in sync on tax classification. Setting up tax codes involves three steps, which must be performed in this order: An active accounting connection GL accounts uploaded (required for associating tax rates with GL accounts) accounting:read and accounting:write scopes Tax rates define the individual rate values (e.g., GST at 5%, PST at 7%) that will be available as options within a tax code. Upload them first using POST /developer/v1/accounting/tax/rates: id Your ERP's external identifier for this tax rate name Display name of the tax rate rate Decimal value (e.g., "0.05" for 5%) accounting_gl_account_id The ramp_id of the GL account to associate with this tax rate. Required for API-based connections. Use GET /developer/v1/accounting/accounts to find the ramp_id. You can upload up to 500 tax rates per request. Batches are all-or-nothing: if any rate fails validation, the entire batch is rejected. One tax code field per connection You only need to create the tax code field once. If the tax code field already exists, skip to Step 3. The tax code field is the accounting field that holds your tax code options. There can only be one active tax code field per accounting connection, so you only need to perform this step once. Use POST /developer/v1/accounting/tax/code to create it: Name of the tax code field in your ERP system display_name The label shown to users in Ramp (optional) Tax code options are the selectable values within your tax code field. Each option can reference one or more tax rates from Step 1. Use POST /developer/v1/accounting/tax/code/options to create them. options[].id Your ERP's external identifier for this option options[].name Display name of the option options[].tax_rate_ids List of tax rate remote IDs (from Step 1) to associate with this option You can upload up to 500 options per request. Once tax code options are uploaded, a Tax Code field will appear to end users as a selectable coding field on transactions in Ramp. After a user selects a tax code, it will appear in the accounting_field_selections array for line items when fetching transactions. For example, when fetching a transaction that was coded with the tax codes uploaded above: The tax code selection has "type": "TAX_CODE" in both the field entry and its category_info, making it easy to identify programmatically. --- title: Vendor Credits source_url: /developer-api/v1/vendor-credits text_url: /llms-guides/vendor-credits.txt summary: This guide explains how integrators can enable and use vendor credits with the Ramp API. content: This guide explains how integrators can enable and use vendor credits with the Ramp API. Note: This feature is currently in Beta. Requirements Your app must have scopes accounting:read, accounting:write, and vendors:read Note This setting is managed at the Accounting Connection level. If you plan on creating multiple Accounting Connections, you need to configure this setting for each connection. For new connections: Make a POST call to /developer/v1/accounting/connection with settings.vendor_credits_enabled set to true: For existing connections: First, retrieve your connection ID by making a GET call to /developer/v1/accounting/connection: Then make a PATCH call to /developer/v1/accounting/connection/{connection_id} with the id to enable vendor credits: Once vendor credits are enabled, users can create them in the Ramp platform: Navigate to Vendors Click into a specific vendor Click New in the right-hand corner Select Vendor Credit and fill in the required fields To list all vendor credits, make a GET call to /developer/v1/vendors/credits: Example response: List vendor credits for a specific vendor To retrieve all vendor credits associated with a specific vendor, make a GET call to /developer/v1/vendors/{vendor_id}/credits. Use the vendor_id from the response above or from your vendor records: This endpoint returns the same response format as the general credits list, but filtered to only include credits for the specified vendor. To retrieve a specific vendor credit, make a GET call to /developer/v1/vendors/credits: --- title: Virtual Cards source_url: /developer-api/v1/virtual-cards text_url: /llms-guides/virtual-cards.txt summary: Due to PCI compliance requirements, 16-digit card numbers and CVVs are not available in production without approval. All customers will see these fields in Sandbox. Submit a Developer API support ticket to begin the qualification process for access. content: Due to PCI compliance requirements, 16-digit card numbers and CVVs are not available in production without approval. All customers will see these fields in Sandbox. Submit a Developer API support ticket to begin the qualification process for access. Create and manage virtual cards with customizable spend and fraud controls, so you can safely embed payments into your apps, agents, or backend workflows. For delivering virtual cards to vendors without PCI compliance requirements, see the card payment options in our Bill Pay guide. For managing physical cards and funds, see our Cards and Funds guide. Travel Platforms - Generate single-use virtual cards for each booking to streamline reconciliation and simplify refund workflows B2B Marketplaces - Provide instant supplier payments via virtual cards while earning interchange on each transaction Procurement & AP Platforms - Replace ACH payments with card AI Agents - Enable AI agents to make autonomous payments with controlled spending limits and merchant restrictions How It Works A virtual card is generated instantly via Ramp’s API, optionally configured with: Merchant restrictions – limiting transactions to specific providers (such as airlines or hotels) Spending caps – ensuring charges do not exceed predefined thresholds Expiration dates – to auto-expire unused cards for security and refund alignment The generated card details (PAN, CVV, expiration) are securely delivered via Ramp’s Vault API. You pass these details to your vendor, travel partner, or supplier to process payment. After the card is charged, Ramp notifies you via webhook and exposes detailed transaction metadata via API. Card ID → Transaction mapping makes it easy to automate reconciliation Supports adjustments & refunds even after the card is locked or expired Webhooks are supported for notifications when a card is used, declined, or refunded Use the following python snippets to instantiate an API client, make your first limit (virtual card), and pull its PAN/CVV. You can issue a virtual card and retrieve sensitive card details in one single synchronous API request. You must have the cards:read_vault limits:write (and optionally, users:read) scopes enabled to run the sample code. You’ll need to update constants like credentials and user information throughout and ensure your Python environment includes the following packages: python-dotenv requests Copy your Client ID and Client Secret into a file named .env. The format should be: In a separate python script: At this point, CLIENT is an authenticated Ramp Developer API client. To create cards we'll use a single synchronous API request to create a limit (with an associated virtual card) and retrieve card number information. Terminating Virtual Cards When you need to permanently terminate a virtual card created via the Vault API, use the limits termination endpoint, not the cards termination endpoint. Virtual cards created through POST /vault/cards return both a spend_limit_id and a card.id. To terminate these cards: ✅ Correct: Use POST /developer/v1/limits/{spend_limit_id}/deferred/termination ❌ Incorrect: Don't use POST /developer/v1/cards/{card_id}/deferred/termination The vault API creates a spend limit with an associated virtual card. Since the card is tied to the limit, you must terminate the limit using its spend_limit_id. Terminating the limit will automatically terminate the virtual card that's associated with that limit. Note that termination is irreversible and processed asynchronously. You can check the task status using the deferred tasks endpoint. FAQ Need help? Submit a Developer API support ticket and our team will follow up. Yes, refunds can be applied even after the card is locked, ensuring reconciliation remains seamless. Ramp offers dedicated support, including access to a sandbox environment, technical documentation, and a partnerships team to guide you through implementation. Subscribe to the transactions.cleared webhook event. This event fires not only when a transaction settles, but also when refunds or reversals are processed on the card. When the webhook fires, fetch the transaction details via the API to check the amount field—a negative amount indicates a refund or reversal. See our Webhooks Guide for setup instructions. --- title: Embedded Cards source_url: /developer-api/v1/virtual-cards-embedded text_url: /llms-guides/virtual-cards-embedded.txt summary: Ramp Embedded Cards allow you to securely display card numbers and CVV codes to users via an iframe. If you want to programmatically create cards for a virtual card issuing flow where partners can easily create virtual cards to pay travel, maintenance, and other third-party vendors on their own platforms, see our Virtual Cards guide. content: Ramp Embedded Cards allow you to securely display card numbers and CVV codes to users via an iframe. If you want to programmatically create cards for a virtual card issuing flow where partners can easily create virtual cards to pay travel, maintenance, and other third-party vendors on their own platforms, see our Virtual Cards guide. This guide walks you through embedding Ramp card details in your application. Card numbers and CVV codes are securely displayed to your users via an iframe—card data flows directly from Ramp to your user's browser without touching your servers. Prerequisites: This guide assumes you have already created a fund and have the card_id of a card you want to display to your end users, and that you have a domain where your application is hosted (parent_origin). For information on creating funds and issuing cards, see our Cards and Funds guide. For more on parent_origin, see the parent_origin section below. Security Notice Never store tokens client-side. All tokens should be securely stored on your backend server. Beta Feature Embedded Cards is currently in beta. Please reach out via the support ticket submission flow to request a whitelist for your parent_origin. This is required before you can generate embed tokens for your domain. This integration follows a four-step flow: Create a limit → Create a limit using POST /limits. A card will be automatically created and each card has a unique card_id Backend generates embed token → Your backend calls /developer/v1/embedded/cards/{card_id}/embed to generate a secure embed token Frontend loads iframe → Your frontend receives the token and loads it in an iframe pointing to Ramp's embed service User views card → The user's browser requests card details directly from Ramp—card data never touches your servers Step 1: Enable the embedded_cards Scope Before you can generate embed tokens, you need to enable the embedded_cards:write scope on your application. Enable the embedded_cards:write scope on your app in the developer dashboard. The embedded_cards:write scope requires explicit approval for production use. Contact the developer support team with the client ID of the app you want this scope enabled for: developer-support@ramp.com Create an API endpoint that accepts a card_id and parent_origin, then calls Ramp's API (POST /embedded/cards/{card_id}/embed) to generate an embed token. Request body: Response: Step 3: Implement Frontend Your frontend calls your backend endpoint to get the embed token, then loads the iframe. Step 4: Testing Your Integration Navigate to the Embedded Card Demo, paste your embed_init_token, and press Load Embed to test the integration. The parent_origin is the domain where your application is hosted. This must exactly match the window.location.origin of the page where you'll embed the iframe. This is a critical security parameter—Ramp validates that the embed request is being loaded from the specified origin, preventing unauthorized domains from displaying your users' card details. Examples: Production: "https://your-app-domain.com" Local development: "http://localhost:3000" The origin must match exactly—including protocol (https:// vs http://) and port number. Mismatched origins will result in the embed failing to load. FAQ Questions? Contact us at developer-support@ramp.com You can retrieve card IDs via the Limits API or when creating cards through the Virtual Cards guide. Yes, but you'll need to contact developer-support@ramp.com to enable the embedded_cards:write scope for your production application. The embed will fail to load if the parent_origin doesn't exactly match the origin of the page loading the iframe. Make sure to include the protocol and port number. --- title: Webhooks source_url: /developer-api/v1/webhooks text_url: /llms-guides/webhooks.txt summary: Webhooks allow your application to receive real-time notifications about events that occur in your Ramp account. Instead of polling our API, webhooks push notifications to your specified endpoint whenever an event happens. content: Webhooks allow your application to receive real-time notifications about events that occur in your Ramp account. Instead of polling our API, webhooks push notifications to your specified endpoint whenever an event happens. Key benefits: Instant notification of events like transactions, approvals, or reimbursements Reduces the need for polling APIs to check for updates Enables automation of downstream workflows (e.g., syncing with accounting software) Webhooks are organized by resource type. Your access token must include the appropriate scope to subscribe to events for each resource. Applications applications:read applications.status_updated Application status has changed (e.g., approved, rejected) Transactions transactions:read transactions.ready_for_review Transaction needs review or coding transactions.cleared Transaction has been settled (also fires for refunds and reversals) transactions.authorized Transaction has been authorized transactions.ready_to_sync Transaction is ready to sync to accounting system Bills bills:read bills.created New bill has been created bills.approved Bill has been approved for payment bills.rejected Bill has been rejected bills.paid Bill payment has been completed Purchase Orders purchase_orders:read purchase_orders.created New purchase order has been created purchase_orders.updated Purchase order has been modified purchase_orders.archived Purchase order has been archived Getting Started Set up an HTTPS endpoint (URL) on your server that can receive POST requests from Ramp. Your endpoint must: Be publicly accessible Use HTTPS Return a 2xx status code for successful receipt Process requests within 10 seconds Create a webhook subscription using the /webhooks endpoint. You must have the appropriate scopes in your access token. Ramp will send a POST request with a challenge to your endpoint during setup. Receive the challenge string from Ramp Respond by making a verification API call: Webhook Payload Format All webhook payloads follow this consistent structure: Payload fields: id: Unique event ID (constant across retries) type: Event type from the available events table created_at: Event timestamp in ISO 8601 format business_id: Identifies which business the event belongs to object: Contains the affected resource ID Transaction Event: Bill Event: Purchase Order Event: To get the full resource details, use the resource ID to fetch from the appropriate API endpoint (e.g., /transactions/{id} for transaction events, /reimbursements/{id} for reimbursement events). Verifying Webhook Signatures To help ensure the security of your integration, Ramp includes a cryptographic signature with every webhook event we send. This allows you to verify that the payload was sent by Ramp and hasn't been modified in transit. While payload validation is optional, we recommend implementing it for any production environment. Using a no-code or low-code platform? If you're using a no-code or low-code platform (like Zapier, Make, or Pipedream), you may not have access to custom code for signature verification — and that's okay. Validation is encouraged, but not required for webhooks to work. When you create a webhook subscription, Ramp provides a secret field in the response. You'll use this secret to verify the authenticity of all subsequent webhook events. Every webhook request from Ramp includes an X-Ramp-Signature header, which contains an HMAC-SHA256 hash of the raw request body, signed with your webhook secret. Sample X-Ramp-Signature from Ramp: Delivery and Retry Logic Webhook delivery throughput is not limited on Ramp's end. However, if your endpoint returns a 429 Too Many Requests status, Ramp has built-in mitigations to handle rate limiting gracefully. Ramp's retry behavior depends on the HTTP status code returned by your webhook endpoint: 2xx Delivery successful - no retries 3xx, 4xx (except 429) Instant delivery failure - no retries 429, 5xx (including timeouts) Retry up to 10 times with exponential backoff Retry Timing: Failed deliveries use exponential backoff with jitter, starting between 0-60 seconds and growing exponentially with each failed attempt. Webhook requests timeout after 10 seconds. Important: The same event id is used for all retry attempts, allowing you to implement idempotency checks. Event Ordering: Webhooks may arrive out of order. For example: transactions.authorized might be delayed or retried transactions.cleared may arrive earlier if successful Design your system to handle out-of-order events gracefully by checking the event timestamp and fetching the latest resource state when needed. Best Practices Implement idempotency checks using the event id to handle duplicate deliveries Return 2xx responses within 10 seconds to avoid timeout retries Process payloads asynchronously to respond quickly Log raw payloads for debugging and audit trails Handle retries gracefully - the same event may be delivered up to 10 times for 429/5xx responses Always verify webhook signatures before processing Use HTTPS endpoints to encrypt data in transit Validate event types against your expected events Implement proper error handling for malformed payloads Monitor for failed webhook deliveries Set up alerting for webhook endpoint downtime Managing Webhook Subscriptions Use the same /webhooks endpoints to manage subscriptions for multi-customer applications. The webhook payload always includes a business_id, which can be used to identify the associated business: Troubleshooting Need help? Submit a Developer API support ticket and our team will follow up. Verify your endpoint is publicly accessible and returns 2xx status codes Check that your webhook subscription includes the correct event types Ensure your access token has the required scopes for the events Confirm your endpoint responds within 10 seconds Ramp will retry webhook deliveries with exponential backoff Missed events during extended downtime may not be recoverable Consider implementing a fallback polling mechanism for critical events Delete the existing webhook subscription Create a new subscription with the updated URL Re-verify the new endpoint Use tools like ngrok to expose your local server Use webhook.site to get a temporary URL for testing webhook delivery Test with a small subset of event types initially Monitor webhook logs for successful delivery and processing A developer dashboard for webhook monitoring is coming soon For now, implement comprehensive logging in your webhook handlers Ready to implement webhooks in your integration? Here are some related guides: Accounting Integration: Learn how ready_to_sync webhooks can replace polling in your Accounting Integration Getting Started: Set up authentication and make your first API calls with our Setup Guide Bill Pay: Automate bill payment workflows with our Bill Pay Guide If you have questions or feedback about webhooks, submit a Developer API support ticket – we're here to help make your integration successful.