# Ramp

> Create and manage virtual cards with customizable spend controls for payments, AI agents, and procurement workflows. Supports both production and sandbox environments.

Source: https://cotera.co/docs/reference/tools/individual-tools/ramp

---

**Authentication Type:** OAuth\
**Description:** Create and manage virtual cards with customizable spend controls for payments, AI agents, and procurement workflows. Supports both production and sandbox environments.

***

## Authentication

To authenticate with Ramp, you'll need to create an OAuth application:

1. Follow the [Ramp Developer API Getting Started guide](https://docs.ramp.com/developer-api/v1/getting-started) to create an OAuth application
2. You'll need to provide:
   * **Client ID** - From your Ramp OAuth application
   * **Client Secret** - From your Ramp OAuth application
   * **Domain** - Your Ramp organization domain

**Required Scopes:**

* `users:read` - Look up user information
* `cards:read_vault` - Access card details (PAN, CVV)
* `limits:write` - Create spending limits for cards
* `limits:read` - Read spending limit configurations

***

## Users

Look up Ramp users by email or user ID.

### Get User

Look up a Ramp user by email address or user ID to get their UUID for creating virtual cards.

**Operation Type:** Query (Read)

**Parameters:**

* **email** `string` (nullable): Email address of the user to look up
* **userId** `string` (nullable): Ramp user ID to look up

**Returns:**

* **id** `string`: Unique Ramp user ID (UUID)
* **email** `string`: User email address
* **firstName** `string` (nullable): User first name
* **lastName** `string` (nullable): User last name
* **role** `string` (nullable): User role in the organization

**Example Usage:**

```json
{
  "email": "john.smith@company.com"
}
```

***

## Virtual Cards

Create and manage virtual cards with spending limits and controls.

### Create Virtual Card

Creates a new virtual card with customizable spending limits, merchant restrictions, and expiration dates. The card is generated instantly and can be used for payments.

**Operation Type:** Mutation (Write)

**Parameters:**

* **userId** `string` (required): The Ramp user ID who will own this virtual card
* **displayName** `string` (required): Display name for the virtual card (e.g., "Hotel Booking")
* **spendingLimitAmount** `number` (required): Spending limit amount in cents (e.g., 500000 for $5,000)
* **spendingLimitCurrency** `string` (nullable): Currency code for the spending limit (default: USD)
* **spendingLimitInterval** `string` (required): Spending limit interval: TOTAL, DAILY, WEEKLY, MONTHLY, QUARTERLY, or YEARLY. TOTAL means one-time use.
* **allowedCategories** `array of numbers` (nullable): Array of allowed merchant category codes (e.g., \[18, 20] for travel). If not specified, all categories are allowed.
* **expirationDate** `string` (nullable): Optional expiration date in ISO 8601 format (YYYY-MM-DD). Card will auto-expire after this date.

**Returns:**

* **cardId** `string`: Unique identifier for the created card
* **displayName** `string`: Display name of the card
* **cardNumber** `string` (nullable): 16-digit card number (PAN) - requires PCI compliance
* **cvv** `string` (nullable): Card CVV - requires PCI compliance
* **expirationMonth** `string` (nullable): Card expiration month (MM)
* **expirationYear** `string` (nullable): Card expiration year (YYYY)
* **spendingLimit** `object`: Spending limit configuration
  * **amount** `number`: Spending limit in cents
  * **currency** `string`: Currency code
  * **interval** `string`: Spending interval
* **status** `string`: Card status (e.g., ACTIVE, SUSPENDED)

**Example Usage:**

```json
{
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "displayName": "AWS Infrastructure - Q1 2024",
  "spendingLimitAmount": 500000,
  "spendingLimitCurrency": "USD",
  "spendingLimitInterval": "MONTHLY",
  "allowedCategories": [18, 20],
  "expirationDate": "2024-12-31"
}
```

***

## Common Use Cases

**AI Agent Payments:**

* Create virtual cards for AI agents to make autonomous payments with spending controls
* Set TOTAL spending limits for one-time agent purchases with automatic card expiration
* Restrict AI agent spending to specific merchant categories for security and compliance
* Generate instant virtual cards for agent workflows without manual approval processes

**Vendor & Subscription Management:**

* Create dedicated virtual cards for each SaaS subscription with MONTHLY spending limits
* Issue one-time use cards (TOTAL interval) for trial subscriptions and vendor evaluations
* Set expiration dates to automatically cancel unwanted subscriptions and free trials
* Track vendor spending by assigning unique cards to each service provider

**Team Spend Controls:**

* Issue virtual cards to team members with DAILY or WEEKLY spending limits
* Restrict cards to specific merchant categories (e.g., travel, office supplies)
* Look up user IDs by email to quickly provision cards for new team members
* Create cards with automatic expiration for temporary contractors and project-based work

**Procurement Automation:**

* Generate virtual cards programmatically for approved purchase requests
* Set spending limits that match exact purchase order amounts
* Use merchant category restrictions to enforce procurement policies
* Create audit trails by linking each card to a specific user and purpose