Cards

The Cards API exposes the physical and virtual cards belonging to the business linked to your API Access Token. Both endpoints require the cards:read scope.

GET /api/v1/cards lists the business's physical and virtual cards.

curl "https://rhoapi.rho.co/api/v1/cards?page_size=20&type=virtual&status=active" \
  -H "Authorization: Bearer $RHO_API_TOKEN"

You can filter by:

• user_id: one or more cardholder user IDs
• type: physical or virtual
• status: one or more card lifecycle statuses

Repeat a parameter to match any of its values. Different filters are combined, so a request with type=virtual&status=active returns cards that match both.

An unfiltered list includes canceled and expired cards so their stable IDs can still be joined to historical transactions.

page_size defaults to 20 and can be from 1 to 100. Pass the response's page.next_page_token as page_token to retrieve the next page. Omit page_token for the first page. Page tokens belong to the API version that created them, so restart pagination when migrating from v0 to v1.

{
  "cards": [
    {
      "id": "ab6aee43-3115-47bc-908f-a8c162b8fcee",
      "name": "Travel card",
      "last_4": "0742",
      "type": "virtual",
      "status": "active",
      "cardholder": {
        "user_id": "9e86b9fb-acde-4797-94e8-d10f84974e51",
        "first_name": "Taylor",
        "last_name": "Morgan"
      },
      "spending_limit": {
        "amount": 500000,
        "currency": "USD"
      },
      "spending_limit_type": "monthly",
      "current_spend": {
        "amount": 124500,
        "currency": "USD"
      },
      "pending_spend": {
        "amount": 18500,
        "currency": "USD"
      },
      "spend_period_start": "2026-08-01T04:00:00Z",
      "spend_period_end": "2026-09-01T04:00:00Z",
      "usage_starts_at": null,
      "usage_ends_at": null,
      "billing_address": {
        "street": "100 Crosby St",
        "city": "New York",
        "subdivision": "NY",
        "postal_code": "10012",
        "country_code": "US"
      },
      "shipping_address": null,
      "blocked_categories": [
        {
          "code": "5812",
          "name": "Eating Places and Restaurants"
        }
      ],
      "blocked_merchants": [
        {
          "name": "Example Merchant"
        }
      ]
    }
  ],
  "page": {
    "next_page_token": null
  }
}

Monetary amount values use the currency's smallest unit, such as cents for USD. Limit, spend, and period fields are null when the card has no spending limit, current spend is unavailable, or the period window could not be determined.

High utilization means the next charge can decline. daily, weekly, monthly and quarterly reset on Eastern Time (America/New_York) calendar boundaries. annual resets on the anniversary of when the limit took effect, not on a calendar boundary. The fixed is a lifetime ceiling that does not reset. single_use is spent after one use. Those two have no spend_period_end.

Merchant controls use either the blocked_* fields or the allowed_* fields, never both. Merchant categories contain an ISO 18245 merchant category code and its human-readable name when available. Merchant entries identify merchants by their human-readable name.

GET /api/v1/cards/{id} returns one card by its stable ID. It uses the same Card object as the list endpoint.

curl "https://rhoapi.rho.co/api/v1/cards/ab6aee43-3115-47bc-908f-a8c162b8fcee" \
  -H "Authorization: Bearer $RHO_API_TOKEN"

The endpoint returns 404 when the card does not exist or belongs to another business. Only the last four PAN digits are returned; full card numbers, CVCs, and expiration dates are not available through these endpoints.

Full endpoint catalogue - paths, parameters, response shapes, and required scopes - lives in the API Reference.