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.

When enabled for a physical card, shipment contains the latest carrier-reported delivery details when a shipment has been recorded:

{
  "shipment": {
    "status": "in_transit",
    "tracking_number": "123456789012",
    "estimated_delivery_at": "2026-09-10T20:00:00Z",
    "delivered_at": null
  }
}

Shipment status is separate from the card's top-level lifecycle status. Possible shipment values are:

• created: The shipment record exists, but carrier movement has not been reported.
• in_transit: The carrier is moving the shipment through its network.
• out_for_delivery: The shipment is on its final delivery route.
• delivery_delayed: The carrier has reported a delay. This does not change the top-level card lifecycle status.
• delivery_canceled: The shipment is no longer scheduled for delivery.
• delivered: The carrier has reported delivery as complete.
• unknown: The carrier could not classify the current shipment state.

tracking_number is null until the carrier assigns one. estimated_delivery_at is null when the carrier has no estimate, and delivered_at remains null until delivery. The entire shipment field is omitted for virtual cards and physical cards without a recorded shipment.

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.