List Cards

GET/cardsOpen in the API playground →

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Query Parameters

statusstringquery

Filter by status: ACTIVE, BLOCKED, UNASSIGNED, LOST

typestringquery

Filter by type: PARENT or CHILD

subscriber_idstringquery

Filter by subscriber UUID

searchstringquery

Search by serial number or MAC address

limitintegerquerydefault: 50

Results per page (max 100)

offsetintegerquerydefault: 0

Pagination offset

---

Response

cardsarray

Array of card objects

total_countinteger

Total matching cards

limitinteger

Current page size

offsetinteger

Current offset

---

Examples

Request

cURL - All Cards

curl -X GET "https://demo.api.vultlocal.com/api/v1/cards" \
  -H "Authorization: Bearer olive_live_xxx"

cURL - Active Only

curl -X GET "https://demo.api.vultlocal.com/api/v1/cards?status=ACTIVE&limit=20" \
  -H "Authorization: Bearer olive_live_xxx"

cURL - Unassigned

curl -X GET "https://demo.api.vultlocal.com/api/v1/cards?status=UNASSIGNED" \
  -H "Authorization: Bearer olive_live_xxx"

Response

200 OK

{
  "cards": [
    {
      "serial": "OLIV0001",
      "mac_address": "AA:BB:CC:DD:EE:01",
      "type": "PARENT",
      "status": "ACTIVE",
      "subscriber_id": "sub_abc123",
      "subscriber_name": "John Doe",
      "linked_at": "2025-01-15T10:30:00Z"
    },
    {
      "serial": "OLIV0002",
      "mac_address": "AA:BB:CC:DD:EE:02",
      "type": "CHILD",
      "status": "ACTIVE",
      "subscriber_id": "sub_abc123",
      "parent_serial": "OLIV0001",
      "daily_limit": 5000000,
      "linked_at": "2025-01-16T14:00:00Z"
    },
    {
      "serial": "OLIV0003",
      "mac_address": "AA:BB:CC:DD:EE:03",
      "type": null,
      "status": "UNASSIGNED",
      "subscriber_id": null,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total_count": 1500,
  "limit": 50,
  "offset": 0
}

---

Common Filters

Use Case	Query
Available cards	?status=UNASSIGNED
All blocked cards	?status=BLOCKED
Child cards only	?type=CHILD
Cards for subscriber	?subscriber_id=sub_abc123

---

Errors

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	Insufficient permissions
500	INTERNAL_ERROR	Server error