Conventions

Date and Time

Date and DateTime are represented using a string that conforms to ISO8601; UTC is assumed if no timezone offset is specified. For example,

{
  "created_at": "2022-04-28T21:36:29.604020"
}

Monetary Values

Monetary values are represented by the currency_code and amount. All returned values of currency_code are three-letter acronyms, as defined in ISO4217. There are two representations of amount in the Ramp API.

🚧

Legacy Representation is deprecated

All legacy representation amounts will be replaced by canonical representations in future releases. We continue to support legacy representations in certain endpoints for backward compatibility, but strongly encourage using the canonical representation in your application.

Canonical Representation

Canonical representation uses CurrencyAmount type to represent monetary values. It groups amount and currency_code together. amount is an integer in smallest denomination to avoid precision loss. For example, $40 is represented as

{
  "amount": 4000,
  "currency_code": "USD"
}

Below is the schema definition of CurrencyAmount type.

{
   "properties":{
      "amount":{
         "description":"the amount of money represented in the smallest denomination of the currency. For example, when the currency is USD, then the amount is expressed in cents.",
         "type":"integer"
      },
      "currency_code":{
         "default":"USD",
         "description":"The type of currency, in ISO 4217 format. e.g. USD for US dollars",
         "type":"string"
      }
   },
   "required":[
      "amount",
      "currency_code"
   ],
   "type":"object"
}

Legacy Representation

In legacy representation, amount and currency are two separate fields and amount is of decimal type. For example,

{
  "amount": 40.00,
  "currency_code": "USD"
}

Deferred Tasks

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.

{
  "id": "eca553b8-6923-42b2-aea9-8f3c15b079ff"
}

This means that asynchronous task processing has been started. The returned task ID can then be used to call GET /developer/v1/card/deferred/status/eca553b8-6923-42b2-aea9-8f3c15b079ff. One of the following task status enums is returned in response: STARTED, IN_PROGRESS, ERROR, SUCCESS.

{
  "id": "eca553b8-6923-42b2-aea9-8f3c15b079ff",
  "data": {
    "error": null,
    "id": null,
    "misc": null
  },
  "status": "STARTED"
}

Pagination

Pagination allow you to retrieve the entire dataset with a series of requests, and each request fetches a portion of the data set. By loading data in smaller chunks, pagination reduces the amount of data transmitted over the wire and alleviates the load on the servers, thus ensuring faster loading times and a smoother user experience.

Ramp API uses a mechanism called keyset pagination to dive 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.

Here's how keyset pagination works step-by-step:

1. Request the First Page: 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.

   "page": {
     "next": f"https://api.ramp.com/developer/v1/cards?page_size=3&start="2907e304-cac2-4abf-84c4-b3b454ae3b8c
   }
   

2. Fetching Subsequent Pages: 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.
3. Continuing the Process: 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.

Ramp Category Codes

These category codes are used to limit the categories a card can be used for.