> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get card details

> Get a list of cards associated with an account, retrieve details about a given card, or retrieve a card's sensitive data (PIN and CVV) by getting an a

Get a list of cards associated with an account, retrieve details about a given card, or retrieve a card's sensitive data (PIN and CVV) by getting an access token to use with Marqeta's sensitive data widget service.

<Info>
  The endpoints described in this guide are currently in beta mode.
</Info>

## List cards

<Note>
  **GET** `/v2/cards`
</Note>

### Request

Use this request to get a list of cards on an account. Results are ordered alphabetically by card name. For every card, you'll get a list of details such as its name, the budget it's linked to, its current state, and more. These don't include its PAN or CVV.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards?accountId=F12345' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that you want to work with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="personId" type="string">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

<ParamField body="limit" type="integer">
  The maximum number of results to return. By default, this is set to `100`.

  Allowable values: `[ 1 .. 1000 ]`
</ParamField>

<ParamField body="offset" type="integer">
  The number of items to skip before returning results. By default, this is set to `0`.

  Allowable values: A valid integer
</ParamField>

<ParamField body="state" type="array of strings">
  The state of the card. Use commas to pass multiple values. Has to be URL encoded. For example, `state=ACTIVE%2CSUSPENDED`.

  Allowable values: `ACTIVE`, `REPLACED`, `TERMINATED`, `SUSPENDED`, `UNACTIVATED`
</ParamField>

<ParamField body="orderBy" type="string">
  The order in which to return the results. By default, this is set to `asc`.

  Allowable values: `asc`, `desc`
</ParamField>

<ParamField body="startDate" type="string">
  The earliest date after which to retrieve records (inclusive).

  Allowable values: Format: `YYYY-MM-DD`
</ParamField>

<ParamField body="endDate" type="string">
  The latest date until which to retrieve records to (inclusive).

  Allowable values: Format: `YYYY-MM-DD`
</ParamField>

<ParamField body="search" type="string">
  The term to search records for. For example, `search=Jane`.

  Allowable values: A valid string
</ParamField>

<ParamField body="budgetId" type="string">
  The ID of the budget that you want to filter results by.

  Allowable values: An existing `budgetId` (≤ 36 characters)
</ParamField>

<ParamField body="cardId" type="string">
  The ID of the card that you want to filter results by.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

<ParamField body="cardIds" type="array of strings">
  An array of card IDs that you want to filter results by.

  Allowable values: An array of existing `cardId`s (≤ 36 characters)
</ParamField>

<ParamField body="personIds" type="array of strings">
  An array of person IDs that you want to filter results by.

  Allowable values: An array of existing `personId`s (≤ 36 characters)
</ParamField>

### Response

If your request is successful, you'll receive a `200` response. By default, this endpoint returns all cards associated with an account, regardless of their state. This includes cards in all states. To filter cards by specific states, use the state query parameter.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "count": 3,
    "limit": 100,
    "offset": 0,
    "rows": [
      {
        "id": "d5d878eb-9418-4b2a-a00f-17fe801c6df2",
        "name": "Travel expenses",
        "personId": "cfd2431d-a682-4167-adfa-5975bc47aaf5",
        "accountId": "F12345",
        "state": "ACTIVE",
        "cardType": "VIRTUAL_PAN",
        "lastFour": "7813",
        "cardProductToken": "23ada04b-5b3b-4b73-8343-da3f14d8d96f",
        "fulfillmentStatus": "ISSUED",
        "expiration": "0128",
        "pinIsSet": false,
        "recipientAddress": null,
        "cardPersonalization": null,
        "careOfLine": null,
        "budgetCardPhoneNumber": null,
        "userTokenId": "5609caee-f89d-4e49-8d2e-6e4d8f8d0422",
        "cardOwnerType": "PEOPLE",
        "budgetCardPhoneNumberPersonId": null,
        "cardGroupId": "d5d878eb-9418-4b2a-a00f-17fe801c6df2",
        "cardProductId": "029bddac-7ef0-11ee-8764-06395f802f08",
        "physicalCardState": "NOT_REQUESTED",
        "physicalCardId": null,
        "forceChangePin": false,
        "createdAt": "2024-01-10T13:39:33.000Z",
        "updatedAt": "2024-01-10T13:40:53.000Z",
        "token": {
          "id": "5609caee-f89d-4e49-8d2e-6e4d8f8d0422",
          "personId": "cfd2431d-a682-4167-adfa-5975bc47aaf5",
          "accountId": "F51310",
          "userToken": "c8b9f4a6-b254-4b01-a3b3-9c266980e36c",
          "budgetId": null
        },
        "meta": [
          {
            "id": "38e0958a-c9d9-4924-959e-36638970439f",
            "cardId": "d5d878eb-9418-4b2a-a00f-17fe801c6df2",
            "metaKey": "stateReason",
            "metaValue": "New card",
            "createdAt": "2024-01-10T13:39:33.000Z",
            "updatedAt": "2024-01-10T13:39:33.000Z",
            "CardId": "d5d878eb-9418-4b2a-a00f-17fe801c6df2"
          },
          {
            "id": "972753a6-384b-4855-ba13-f571c20ce109",
            "cardId": "d5d878eb-9418-4b2a-a00f-17fe801c6df2",
            "metaKey": "expirationTime",
            "metaValue": "2028-01-31T23:59:59Z",
            "createdAt": "2024-01-10T13:39:33.000Z",
            "updatedAt": "2024-01-10T13:39:33.000Z",
            "CardId": "d5d878eb-9418-4b2a-a00f-17fe801c6df2"
          }
        ],
        "budget": {
          "id": "0ca2bb87-4d5b-4b14-99c8-cbb8fccff45b",
          "name": "Account balance"
        }
      },
      {
        "id": "800065b2-4d12-42ac-940c-00cd930e3758",
        "name": "Marketing",
        "personId": "cfd2431d-a682-4167-adfa-5975bc47aaf5",
        "accountId": "F12345",
        "state": "ACTIVE",
        "cardType": "VIRTUAL_PAN",
        "lastFour": "3315",
        "cardProductToken": "23ada04b-5b3b-4b73-8343-da3f14d8d96f",
        "fulfillmentStatus": "ISSUED",
        "expiration": "0128",
        "pinIsSet": false,
        "recipientAddress": {
          "city": "Porterville",
          "country": "US",
          "address1": "123 Henry St",
          "lastName": "Doe",
          "firstName": "Jane",
          "postalCode": "93257"
        },
        "cardPersonalization": null,
        "careOfLine": null,
        "budgetCardPhoneNumber": null,
        "userTokenId": "5609caee-f89d-4e49-8d2e-6e4d8f8d0422",
        "cardOwnerType": "PEOPLE",
        "budgetCardPhoneNumberPersonId": null,
        "cardGroupId": "800065b2-4d12-42ac-940c-00cd930e3758",
        "cardProductId": "029bddac-7ef0-11ee-8764-06395f802f08",
        "physicalCardState": "PENDING_ACTIVATION",
        "physicalCardId": "0302fbed-6078-4497-a580-61ad686eb228",
        "forceChangePin": false,
        "createdAt": "2024-01-18T13:42:51.000Z",
        "updatedAt": "2024-01-18T13:53:01.000Z",
        "token": {
          "id": "5609caee-f89d-4e49-8d2e-6e4d8f8d0422",
          "personId": "cfd2431d-a682-4167-adfa-5975bc47aaf5",
          "accountId": "F12345",
          "userToken": "c8b9f4a6-b254-4b01-a3b3-9c266980e36c",
          "budgetId": null
        },
        "meta": [
          {
            "id": "8a98c26c-8196-4f40-ba72-037569a0a8d0",
            "cardId": "800065b2-4d12-42ac-940c-00cd930e3758",
            "metaKey": "expirationTime",
            "metaValue": "2028-01-31T23:59:59Z",
            "createdAt": "2024-01-18T13:42:51.000Z",
            "updatedAt": "2024-01-18T13:42:51.000Z",
            "CardId": "800065b2-4d12-42ac-940c-00cd930e3758"
          },
          {
            "id": "ee473b51-d16b-429d-8017-d13cd2361925",
            "cardId": "800065b2-4d12-42ac-940c-00cd930e3758",
            "metaKey": "stateReason",
            "metaValue": "New card",
            "createdAt": "2024-01-18T13:42:51.000Z",
            "updatedAt": "2024-01-18T13:42:51.000Z",
            "CardId": "800065b2-4d12-42ac-940c-00cd930e3758"
          }
        ],
        "budget": {
          "id": "0ca2bb87-4d5b-4b14-99c8-cbb8fccff45b",
          "name": "Account balance"
        }
      },
      {
        "id": "5bff4edb-df84-4db3-bbef-e2a71fb99bce",
        "name": "Team party",
        "personId": "cfd2431d-a682-4167-adfa-5975bc47aaf5",
        "accountId": "F12345",
        "state": "ACTIVE",
        "cardType": "VIRTUAL_PAN",
        "lastFour": "0231",
        "cardProductToken": "23ada04b-5b3b-4b73-8343-da3f14d8d96f",
        "fulfillmentStatus": "ISSUED",
        "expiration": "0128",
        "pinIsSet": false,
        "recipientAddress": null,
        "cardPersonalization": null,
        "careOfLine": null,
        "budgetCardPhoneNumber": null,
        "userTokenId": "5609caee-f89d-4e49-8d2e-6e4d8f8d0422",
        "cardOwnerType": "PEOPLE",
        "budgetCardPhoneNumberPersonId": null,
        "cardGroupId": "5bff4edb-df84-4db3-bbef-e2a71fb99bce",
        "cardProductId": "029bddac-7ef0-11ee-8764-06395f802f08",
        "physicalCardState": "NOT_REQUESTED",
        "physicalCardId": null,
        "forceChangePin": false,
        "createdAt": "2024-01-08T16:26:26.000Z",
        "updatedAt": "2024-01-10T11:38:40.000Z",
        "token": {
          "id": "5609caee-f89d-4e49-8d2e-6e4d8f8d0422",
          "personId": "cfd2431d-a682-4167-adfa-5975bc47aaf5",
          "accountId": "F12345",
          "userToken": "c8b9f4a6-b254-4b01-a3b3-9c266980e36c",
          "budgetId": null
        },
        "meta": [
          {
            "id": "170f61d4-9711-408a-9f3e-fbb4601f8d9a",
            "cardId": "5bff4edb-df84-4db3-bbef-e2a71fb99bce",
            "metaKey": "expirationTime",
            "metaValue": "2028-01-31T23:59:59Z",
            "createdAt": "2024-01-08T16:26:26.000Z",
            "updatedAt": "2024-01-08T16:26:26.000Z",
            "CardId": "5bff4edb-df84-4db3-bbef-e2a71fb99bce"
          },
          {
            "id": "1f93ba30-8f0b-4116-9198-afe896821d3c",
            "cardId": "5bff4edb-df84-4db3-bbef-e2a71fb99bce",
            "metaKey": "stateReason",
            "metaValue": "New card",
            "createdAt": "2024-01-08T16:26:26.000Z",
            "updatedAt": "2024-01-08T16:26:26.000Z",
            "CardId": "5bff4edb-df84-4db3-bbef-e2a71fb99bce"
          }
        ],
        "budget": {
          "id": "0ca2bb87-4d5b-4b14-99c8-cbb8fccff45b",
          "name": "Account balance"
        }
      }
    ]
  }
  ```

  ```json Response structure theme={null}
  {
    "limit": integer,
    "offset": integer,
    "count": integer,
    "search": "string",
    "rows": [
      {
        "id": "string",
        "personId": "string",
        "accountId": "string",
        "cardProductName": "string",
        "lastFour": "string",
        "expiration": "string",
        "expirationTime": "string",
        "pinIsSet": boolean,
        "state": "string",
        "stateReason": "string",
        "fulfillmentStatus": "string",
        "cardType": "string",
        "recipientAddress": {
          "firstName": "string",
          "middleName": "string",
          "lastName": "string",
          "address1": "string",
          "address2": "string",
          "city": "string",
          "state": "string",
          "postalCode": "string",
          "country": "string",
          "phone": "string"
        },
        "cardOwnerType": "string",
        "name": "string",
        "budgetCardPhoneNumber": "string",
        "meta": [
          {
            "id": "string",
            "cardId": "string",
            "metaKey": "string",
            "metaValue": "string"
          }
        ],
        "budgets": [
          {
            "id": "string",
            "name": "string"
          }
        ],
        "budget": {
          "id": "string",
          "name": "string"
        },
        "spendingLimit": {
          "id": "string",
          "amount": number,
          "active": boolean,
          "limitTurnedOff": boolean,
          "limitWindow": "string",
          "available": {
            "uses": number,
            "amount": number,
            "daysRemaining": number
          }
        },
        "transactionLimit": {
          "id": "string",
          "amount": number,
          "active": boolean,
          "limitTurnedOff": boolean,
          "limitWindow": "string"
        },
        "budgetCardPhoneNumberPersonId": "string",
        "previousCards": [
          null
        ],
        "currencies": [
          {
            "numericCode": "string",
            "code": "string"
          }
        ],
        "physicalCardState": "string",
        "physicalCardId": "string",
        "forceChangePin": boolean,
        "createdAt": "string",
        "updatedAt": "string"
      }
    ]
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/card-details/list-cards).

## Retrieve a card

<Note>
  **GET** `/v2/cards/{cardId}`
</Note>

### Request

Use this request to get details about a given card. These include its name, the budget it's linked to, and its current state, but not its PAN and CVV.

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd?accountId=F12345' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/{cardId}?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

You can use the optional `include` parameter to retrieve additional information, such as the card's spending and transaction limits.

#### Path parameters

<ParamField body="cardId" type="string" required>
  The ID of the card for which you want to get details.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="personId" type="string">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

<ParamField body="include" type="string">
  Optional embeds to include when returning card details.

  Allowable values: `limits`, `cardProduct`
</ParamField>

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "id": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
    "personId": "f3e5ff26-28ff-4cd6-9b1b-e303a185a13a",
    "accountId": "F12345",
    "cardProductName": "string",
    "lastFour": "0056",
    "expiration": "0111",
    "expirationTime": "2025-01-31T23:59:59Z",
    "pinIsSet": true,
    "state": "ACTIVE",
    "stateReason": "New card",
    "fulfillmentStatus": "ISSUED",
    "cardType": "PHYSICAL_MSR",
    "recipientAddress": {
      "firstName": "Jane",
      "middleName": "Roger",
      "lastName": "Doe",
      "address1": "123 Henry St",
      "address2": "Suite 101",
      "city": "Porterville",
      "state": "CA",
      "postalCode": "93257",
      "country": "US",
      "phone": "8315555555"
    },
    "cardOwnerType": "PEOPLE",
    "name": "Team Party Card",
    "budgetCardPhoneNumber": "+447911001762",
    "meta": [
      {
        "id": "string",
        "cardId": "e9293471-5eb3-4dbc-916c-dbaf9e2deefd",
        "metaKey": "expirationTime",
        "metaValue": "New card"
      }
    ],
    "budgets": [
      {
        "id": "775596ae-2624-40af-a9dc-9756110a4a03",
        "name": "Engineering"
      }
    ],
    "budget": {
      "id": "775596ae-2624-40af-a9dc-9756110a4a03",
      "name": "Engineering"
    },
    "spendingLimit": {
      "id": "775596ae-2624-40af-a9dc-9756110a4a03",
      "amount": 100.5,
      "active": false,
      "limitTurnedOff": true,
      "limitWindow": "DAY",
      "available": {
        "uses": 0,
        "amount": 100.5,
        "daysRemaining": 1
      }
    },
    "transactionLimit": {
      "id": "775596ae-2624-40af-a9dc-9756110a4a03",
      "amount": 100.5,
      "active": false,
      "limitTurnedOff": true,
      "limitWindow": "TRANSACTION"
    },
    "budgetCardPhoneNumberPersonId": "775596ae-2624-40af-a9dc-9756110a4a08",
    "previousCards": [
      null
    ],
    "currencies": [
      {
        "numericCode": "840",
        "code": "USD"
      }
    ],
    "physicalCardState": "ACTIVE",
    "physicalCardId": "884496ae-2624-40af-a9dc-9756110a4a18",
    "forceChangePin": false,
    "createdAt": "2021-01-30T08:30:00Z",
    "updatedAt": "2021-01-30T08:30:00Z"
  }
  ```

  ```json Response structure theme={null}
  {
    "id": "string",
    "personId": "string",
    "accountId": "string",
    "cardProductName": "string",
    "lastFour": "string",
    "expiration": "string",
    "expirationTime": "string",
    "pinIsSet": boolean,
    "state": "string",
    "stateReason": "string",
    "fulfillmentStatus": "string",
    "cardType": "string",
    "recipientAddress": {
      "firstName": "string",
      "middleName": "string",
      "lastName": "string",
      "address1": "string",
      "address2": "string",
      "city": "string",
      "state": "string",
      "postalCode": "string",
      "country": "string",
      "phone": "string"
    },
    "cardOwnerType": "string",
    "name": "string",
    "budgetCardPhoneNumber": "string",
    "meta": [
      {
        "id": "string",
        "cardId": "string",
        "metaKey": "string",
        "metaValue": "string"
      }
    ],
    "budgets": [
      {
        "id": "string",
        "name": "string"
      }
    ],
    "budget": {
      "id": "string",
      "name": "string"
    },
    "spendingLimit": {
      "id": "string",
      "amount": number,
      "active": boolean,
      "limitTurnedOff": boolean,
      "limitWindow": "string",
      "available": {
        "uses": number,
        "amount": number,
        "daysRemaining": number
      }
    },
    "transactionLimit": {
      "id": "string",
      "amount": number,
      "active": boolean,
      "limitTurnedOff": boolean,
      "limitWindow": "string"
    },
    "budgetCardPhoneNumberPersonId": "string",
    "previousCards": [
      null
    ],
    "currencies": [
      {
        "numericCode": "string",
        "code": "string"
      }
    ],
    "physicalCardState": "string",
    "physicalCardId": "string",
    "forceChangePin": boolean,
    "createdAt": "string",
    "updatedAt": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/card-details/retrieve-a-card).

## Retrieve a card's sensitive data

<Note>
  **GET** `/v2/cards/{cardId}/access-token`
</Note>

### Request

Use this request to retrieve an access token, which you can use to get a card's sensitive date (PAN and CVV) via [Marqeta's sensitive data widget service](https://www.marqeta.com/docs/developer-guides/using-marqeta-js#_card_data_tutorial).

<Info>
  Access tokens expire after 5 minutes.
</Info>

<CodeGroup>
  ```bash Sample request theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/e9293471-5eb3-4dbc-916c-dbaf9e2deefd/access-token?accountId=F12345' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```

  ```bash Request structure theme={null}
  curl -i -X GET \
    'https://api.equalsmoney.com/v2/cards/{cardId}/access-token?accountId={accountId}' \
    -H 'Authorization: ApiKey YOUR_API_KEY_HERE'
  ```
</CodeGroup>

#### Path parameters

<ParamField body="cardId" type="string" required>
  The ID of the card for which you want to get details.

  Allowable values: An existing `cardId` (≤ 36 characters)
</ParamField>

#### Query parameters

<ParamField body="accountId" type="string" required>
  The ID of the account that the card is associated with.

  Allowable values: An existing `accountId`
</ParamField>

<ParamField body="personId" type="string">
  The ID of the person that the card belongs to.

  Allowable values: An existing `personId` (≤ 36 characters)
</ParamField>

### Response

If your request is successful, you'll receive a `200` response.

<CodeGroup>
  ```json Sample response theme={null}
  {
    "token": "b2lsYWdhaW5zdG1vdGhlcmZvZ3B1cGlsY2FtcG5pbmVjcm93ZGZvdWdodGFnYWluc3R0dXJuY2xvdGhzaWxlbnRzYXdjYXJyaWVkbm90aGluZ2Z1bGx5d2hlbmV2ZXJseWluZ2J1dGNoYXB0ZXJzbWlsZWRpc3RhbnRyZXNlYXJjaHN1bW1lcmRhbmNlbGlrZWx5Zml4YWR2aWNlbWFnbmV0cmV0dXJubWFya2V0cGVyZmVjdGJlZ2Fub3V0c2lkZXdlaWdocGFwZXJzaGVub3VuZ2l2ZW5iYXR0bGVtZXRicmVhZHN0ZXBncmFpbmludGVyaW9yc2xlcHRtdXN0YmxhbmtldHNpbGVuY2VicmFuY2hwcm91ZHByb2R1Y2Vsb3dlcnRoZW9yeXN1cHBvcnRuZXdzcGFwZXJvcmdhbml6ZWRjYXJkdHdvdG9tb3Jyb3d2YXBvcmNvbmRpdGlvbnNtb2tlaG93ZXZlcmNhZ2Vyb2NraGlzdG9yeXVzZWhvcGVkaXJ0eW1vdW50YWluZHJlc3NkYW5jZXF1aWNrZWlnaHRkaXZpc2lvbnRlbXBlcmF0dXJlYW55aW1hZ2luZWNvbXBsZXRlbHlwcmVzZW50c3BlY2lmaWNhYm91dGdyYWRld291bGRnZW50bGVjcm9zc2ZyaWdodGVuYmVlZ2F2ZXNjaWVuY2Vob3JzZXBhbmJlY2F1c2VzaG9ydGxlYXJucmVjZW50bHlkb3plbm15c3RlcmlvdXNzaGVwaWVkaXN0YW50cmVhbGl6ZW5pZ2h0ZmF0aGVyY29tcGxleHJlc3RmdXJ0aGVyZXhwbG9yZWNvbG9ueW1hcG9sZGVycmVjZW50bHlwYW55b3Vyc2VsZmN1cnZlbmVpZ2hib3Job29kc2VudGVuY2VhZHZlbnR1cmVzdGFpcnNtZWV0c2lnaHRwbGF0ZXNkaXZpZGVtaXNzaW5nYmVhdXR5cmFuZ2VuaW5ld3JpdGVyc3RvcnlkaXNjdXNzaW9uZGVwZW5kaGlzaW5jbHVkZXNhdGVsbGl0ZXN0aGVtc2VsdmVzZ2VuZXJhbGJpdGxlZnRmYXJ0aGVyYnJpbmcx"
  }
  ```

  ```json Response structure theme={null}
  {
    "token": "string"
  }
  ```
</CodeGroup>

For more detailed information about this request and its response, [see the API reference](/api-reference/card-details/retrieve-an-access-token-for-card-data-and-digital-wallet-operations).