---
title: "Card Details"
method: POST
path: "/cards/details"
tags: ["Cards"]
---

# Card Details

`POST /cards/details`

Returns card details for one or more cards depending on the given input. You can also request card details per cardholder(s) or organization(s). 
The API returns all card details to the given input which can be found in the system. So you can also combine the different input fields (OR relation). 
Be aware that the usage of [cardholder](/docs/cardholder-entity) or organizations IDs most likely add multiple card details themselves. Also cardholders can be part of multiple organizations, thus when searching via [cardholder](/docs/cardholder-entity) IDs, it might return more data than it would for just one organization this [cardholder](/docs/cardholder-entity) is part of. 
At least one parameter has to be set.

**This endpoint has changed in comparison to the previous version of the API.** The following changes were made:
- added `cardControls` to response body
- changed the enumeration for the status field in the response body
- deprecated `type` and replaced it with `cardConfig`

## Request body

- object
  - `cardIds` string[]
  - `cardholderIds` string[]
  - `organizationIds` string[]
  - `pagination` object
    - `page` integer — The page number to return, starting with 0, this counts up to the total number of pages. The total number of pages is determined by the total number of records divided by the limit.
    - `limit` integer — The number of records to return per page.
    - `sortBy` object — The field to sort by and the direction to sort by.
      - `field` 'organizationId' | 'status' | 'cardholderId' | 'updatedAt' — The field to sort by.
      - `direction` 'ASC' | 'DESC' — The direction to sort by.

## Response `200`

Ok

- object
  - `data` object[]
    - `cardId` string, uuid — The unique identifier of the card.
    - `cardRequestId` string, uuid, nullable — If this card originated from a card request, this field contains the unique identifier of the card request.
    - `organizationId` string, uuid — The unique identifier of the organization, this card belongs to.
    - `cardholderId` string, uuid — The unique identifier of the cardholder, this card belongs to.
    - `cardAccountId` string, uuid — The unique identifier of the card account, this card belongs to.
    - `type` 'VIRTUAL' | 'SINGLE_USE' | 'PHYSICAL' | 'BLACK' | 'TRAVEL', nullable — Deprecated, please use `cardConfig` instead. `VIRTUAL` - Virtual credit card `SINGLE_USE` - One-time virtual credit card (only one authorization allowed per card) `PHYSICAL` - Physical credit card `BLACK` - Physical black premium credit card `TRAVEL` - Virtual cards used specifically in travel industry related use cases
    - `cardConfig` string — The Pliant card configuration of this card. This describes all feature of this card in one single configuration, e.g. the type of the card and also the design of the card etc. It replaces the deprecated card `type`. Please refer to the [guide section](/docs/card-entity) to learn more about possible values.
    - `status` 'PENDING' | 'PENDING_ACTIVATION' | 'PENDING_ISSUANCE' | 'PENDING_REGISTRATION' | 'REQUEST_APPROVED' | 'REQUESTED' | 'REQUEST_CANCELLED' | 'REQUEST_REJECTED' | 'ACTIVE' | 'LOCKED' | 'LOCKED_PIN' | 'EXPIRED' | 'TERMINATED' | 'TERMINATED_LOST' | 'TERMINATED_STOLEN' — The status of the card. **Deprecation Notice:** The status values `PENDING_ACTIVATION`, `PENDING_ISSUANCE`, and `PENDING_REGISTRATION` are deprecated and will be mapped to `PENDING` with appropriate `pendingDetails` in the future. Use `PENDING` with the corresponding `pendingDetails` value instead.
    - `pendingDetails` 'PENDING_ACTIVATION' | 'PENDING_ISSUANCE' | 'PENDING_REGISTRATION' | 'PENDING_VALIDITY' | 'PENDING_SANCTION_SCREEN' | 'PENDING_INFORMATION', nullable — The internal reason for a card's pending state. This field is only populated when `status` is `PENDING` or one of the deprecated `PENDING_...` statuses, and will be `null` for all non-pending statuses.
    - `label` string, nullable — A short text describing the card. Available only for virtual cards with a `cardConfig` containing `VIRTUAL` or `TRAVEL`. The maximum length is 40 characters.
    - `purpose` string, nullable — A short text describing the card. Available only for virtual cards with a `cardConfig` containing `SINGLE_USE`, the maximum length is 40 characters.
    - `refNum` string, nullable — The last 4 digits of the PAN (payment card number), better known as the credit card number. It can be `null` e.g. for terminated cards.
    - `issuingDate` string, date-time, nullable — Date-time of card issuing, e.g. `2023-08-23T14:28:53.600608Z`. Can be null e.g. for cards which are requested by a [cardholder](/docs/cardholder-entity) but the request is declined.
    - `expiryDate` string, date-time, nullable — Date-time (without nanoseconds) when card expires, e.g. `2026-07-31T23:59:59Z`. For cards with type `SINGLE_USE` this is set to 12 months automatically and every value put here is ignored. Can be null e.g. for cards which are requested by a [cardholder](/docs/cardholder-entity) but the request is declined.
    - `limit` object — The limit of the card, describing the overall limit of this card. It might get reset regularly depending on the field `limitRenewFrequency`.
      - `value` number — The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts.
      - `currency` string — The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar.
    - `transactionLimit` object — The transaction limit of the card, describing the maximum amount a single transaction can have on this card.
      - `value` number — The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts.
      - `currency` string — The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar.
    - `spendingBalance` object — The spending balance of the card.
      - `value` number — The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts.
      - `currency` string — The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar.
    - `availableBalance` object — The available balance of the card.
      - `value` number — The value of the monetary amount, converted to minor units of the currency. For instance 1.00 EUR is 100 cents, thus the value here is `100`. See our [guides](/docs/monetary-values) for more details about how to handle monetary amounts.
      - `currency` string — The currency of the monetary amount in ISO 4217 format, for example `EUR` for Euro or `USD` for US Dollar.
    - `token` string — The network token of the card.
    - `cardDesign` string — The card design of the card on Thredd (Pliant's credit card processor) side.
    - `productRef` string — The product reference of the card on Thredd (Pliant's credit card processor) side. This field is deprecated and will be removed in the future. Use `cardDesignId` instead.
    - `platformFee` boolean — Whether the card is used for the internal Pliant platform fee or not.
    - `limitPeriodEnd` string, date-time — Date-time (without nanoseconds) when the current limit period ends, e.g. `2023-09-30T23:59:59Z`.
    - `limitRenewDate` string, date — Date when the limit will be renewed, e.g. `2023-10-01`.
    - `limitRenewFrequency` 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'ANNUAL' | 'TOTAL' — Describes how often the limit of the card is renewed. * `DAILY` - The card limit is renewed every day * `WEEKLY` - The card limit is renewed every week * `MONTHLY` - The card limit is renewed every calendar month * `QUARTERLY` - The card limit is renewed every calendar quarter * `ANNUAL` - The card limit is renewed every year * `TOTAL` - The card limit is never going to be renewed. After the limit is spent the card cannot be used anymore.
    - `customFirstName` string, nullable — Optional first name on `TRAVEL` cards which is used on the card, instead of the regular [cardholder](/docs/cardholder-entity) name. If empty, the regular [cardholder](/docs/cardholder-entity) name is used.
    - `customLastName` string, nullable — Optional last name on `TRAVEL` cards which is used on the card, instead of the regular [cardholder](/docs/cardholder-entity) name. If empty, the regular [cardholder](/docs/cardholder-entity) name is used.
    - `cardControls` 0 — unresolved $ref
    - `replacedByCardId` string, uuid, nullable — Filled, if this card was replaced by another card.
    - `replacedCardId` string, uuid, nullable — Filled, if this card replaced another card.
    - `replacementReason` 'DAMAGED' | 'EXPIRING_SOON' | 'LOST' | 'OTHER' | 'STOLEN', nullable — Describes the reason for the card replacement, if any happened.
    - `shippingDate` string, date-time, nullable — Date-time when the physical card was shipped, e.g. `2023-10-16T11:34:59.595Z`. This field is empty for all other types of cards, or when the physical card is not shipped yet.
    - `panAlias` string, nullable — The PAN alias of the card. This is not the real credit card number (PAN) but a alias version of it.
    - `validFrom` string, date, nullable — Optional field to describe a fixed date range in which the card is usable for purchases. Outside of this date range, the card cannot be used for any purchases, only for zero-amount card-checks, and is shown with `status` `PENDING`. If not provided, the card is active immediately. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the provided date is already a valid day to use the card. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The `validFrom` date needs to be before the `validTo` date. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all.
    - `validTo` string, date, nullable — Optional field to describe a fixed date range in which the card is usable for purchases. After the specified date, the card is automatically terminated. If not provided, the card is active until the `validityPeriod` ends. Date needs to be provided as `yyyy-mm-dd` and is treated inclusive, meaning the card will be terminated one day after this date. If used, the parallel usage of card controls regarding `dates` and/or `times` is not allowed and the `validityPeriod` will be set to 36 months automatically. The earliest possible date is the current date. The latest possible date is the end date of the `validityPeriod`. The fields `validFrom`, `validTo` and `validTimezone` need to be used together, if used at all.
    - `validTimezone` string — Optional field to describe the timezone for the `validFrom` and `validTo` fields. This field is mandatory if `validFrom` and `validTo` fields are used. A list of valid timezones can be found in our [guide section](/docs/card-controls-1).
    - `maxTransactionCount` number — Optional field to describe the maximum number of transactions within the range of `1..999999999` that can be performed with this card. If not provided, the card can be used for an unlimited number of transactions until the card expires.
    - `customFields` Items[] — The [custom fields](/docs/custom-fields-on-transactions) set on this card. These [custom fields](/docs/custom-fields-on-transactions) are used as default values for every transaction made with this card. — unresolved $ref
    - `cardDesignId` string, uuid — The unique identifier of the card design used for this specific card.
    - `cardDesignLogoName` string, nullable — The name of the card design used for this specific card.
    - `maskedPan` string — The masked PAN of the card. This is the real credit card number (PAN) but with the middle digits replaced by `*`. E.g. `481063******6054`.
    - `benefit` boolean — Indicates that the card was issued as an employee benefit.
    - `copilots` object, nullable — Optional feature for `TRAVEL` cards. The copilot also has access to the card and its card details alongside with the cardholder of the card itself.
      - `cardholderIds` string[] — The IDs of the cardholders assigned as copilots to the card.
      - `teamIds` string[] — The IDs of the teams assigned as copilots to the card.
    - `clickToPayInfo` ClickToPayInfo — unresolved $ref
    - `fundingType` 'CHARGE' | 'LOAD_BASED_ACCRUING' | 'LOAD_BASED_NON_ACCRUING' | 'BALANCE_BASED' — * `CHARGE` - normal (non-benefit) credit card * `LOAD_BASED_ACCRUING` - benefit card where money not spent is transferred to the next month * `LOAD_BASED_NON_ACCRUING` - benefit card where money not spent is lost end of month * `BALANCE_BASED` - benefit card with a standing balance that persists across months and is spent down until depleted (no monthly reset).
    - `nextLoadDate` string, date — For cards that are loaded periodically, indicates the date when the card will be loaded the next time.
    - `additionalLimits` Items[] — Additional limits on this card. Empty when none are configured. — unresolved $ref
  - `hasNextPage` boolean — Indicates whether there is a next page available.

## Other responses

- `400` — unresolved $ref
- `401` — unresolved $ref
- `403` — unresolved $ref
- `404` — unresolved $ref
- `429` — unresolved $ref
- `500` — unresolved $ref

---

[API](https://skmtc.dev/getpliant/apis/pliant-customer-api.md) · [All operations](https://skmtc.dev/getpliant/apis/pliant-customer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getpliant/pliant-customer-api/revisions/f3f589cfa718/schema)