---
title: "List all cardholders"
method: GET
path: "/v1/issuing/cardholders"
---

# List all cardholders

`GET /v1/issuing/cardholders`

Returns a list of Issuing `Cardholder` objects. The objects are sorted in descending order by creation date, with the most recently created object appearing first.

## Query parameters

- `created` union
  - object
    - `gt` integer
    - `gte` integer
    - `lt` integer
    - `lte` integer
  - integer
- `email` string
- `ending_before` string
- `expand` string[]
- `limit` integer
- `phone_number` string
- `starting_after` string
- `status` 'active' | 'blocked' | 'inactive'
- `type` 'company' | 'individual'

## Response `200`

Successful response.

- object
  - `data` IssuingCardholder[], required
    - `billing` IssuingCardholderAddress, required
      - `address` Address, required
        - `city` string, nullable — City, district, suburb, town, or village.
        - `country` string, nullable — Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)).
        - `line1` string, nullable — Address line 1, such as the street, PO Box, or company name.
        - `line2` string, nullable — Address line 2, such as the apartment, suite, unit, or building.
        - `postal_code` string, nullable — ZIP or postal code.
        - `state` string, nullable — State, county, province, or region ([ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2)).
    - `company` IssuingCardholderCompany
      - `tax_id_provided` boolean, required — Whether the company's business ID number was provided.
    - `created` integer, required — Time at which the object was created. Measured in seconds since the Unix epoch.
    - `email` string, nullable — The cardholder's email address.
    - `id` string, required — Unique identifier for the object.
    - `individual` IssuingCardholderIndividual
      - `card_issuing` IssuingCardholderCardIssuing
        - `user_terms_acceptance` IssuingCardholderUserTermsAcceptance
          - `date` integer, nullable — The Unix timestamp marking when the cardholder accepted the Authorized User Terms.
          - `ip` string, nullable — The IP address from which the cardholder accepted the Authorized User Terms.
          - `user_agent` string, nullable — The user agent of the browser from which the cardholder accepted the Authorized User Terms.
      - `dob` IssuingCardholderIndividualDob
        - `day` integer, nullable — The day of birth, between 1 and 31.
        - `month` integer, nullable — The month of birth, between 1 and 12.
        - `year` integer, nullable — The four-digit year of birth.
      - `first_name` string, nullable — The first name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.
      - `last_name` string, nullable — The last name of this cardholder. Required before activating Cards. This field cannot contain any numbers, special characters (except periods, commas, hyphens, spaces and apostrophes) or non-latin letters.
      - `verification` IssuingCardholderVerification
        - `document` IssuingCardholderIdDocument
          - `back` union — The back of a document returned by a [file upload](https://api.stripe.com#create_file) with a `purpose` value of `identity_document`.
            - string
            - File — This object represents files hosted on Stripe's servers. You can upload files with the [create file](https://api.stripe.com#create_file) request (for example, when uploading dispute evidence). Stripe also creates files independently (for example, the results of a [Sigma scheduled query](#scheduled_queries)). Related guide: [File upload guide](https://docs.stripe.com/file-upload)
              - …
          - `front` union — The front of a document returned by a [file upload](https://api.stripe.com#create_file) with a `purpose` value of `identity_document`.
            - string
            - File — This object represents files hosted on Stripe's servers. You can upload files with the [create file](https://api.stripe.com#create_file) request (for example, when uploading dispute evidence). Stripe also creates files independently (for example, the results of a [Sigma scheduled query](#scheduled_queries)). Related guide: [File upload guide](https://docs.stripe.com/file-upload)
              - …
    - `livemode` boolean, required — If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
    - `metadata` object, required — Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
    - `name` string, required — The cardholder's name. This will be printed on cards issued to them.
    - `object` 'issuing.cardholder', required — String representing the object's type. Objects of the same type share the same value.
    - `phone_number` string, nullable — The cardholder's phone number. This is required for all cardholders who will be creating EU cards. See the [3D Secure documentation](https://docs.stripe.com/issuing/3d-secure#when-is-3d-secure-applied) for more details.
    - `preferred_locales` string[], nullable — The cardholder’s preferred locales (languages), ordered by preference. Locales can be `da`, `de`, `en`, `es`, `fr`, `it`, `pl`, or `sv`. This changes the language of the [3D Secure flow](https://docs.stripe.com/issuing/3d-secure) and one-time password messages sent to the cardholder.
    - `requirements` IssuingCardholderRequirements, required
      - `disabled_reason` 'listed' | 'rejected.listed' | 'requirements.past_due' | 'under_review', nullable — If `disabled_reason` is present, all cards will decline authorizations with `cardholder_verification_required` reason.
      - `past_due` string[], nullable — Array of fields that need to be collected in order to verify and re-enable the cardholder.
    - `spending_controls` IssuingCardholderAuthorizationControls
      - `allowed_card_presences` string[], nullable — Array of card presence statuses from which authorizations will be allowed. Possible options are `present`, `not_present`. All other statuses will be blocked. Cannot be set with `blocked_card_presences`. Provide an empty value to unset this control.
      - `allowed_categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) of authorizations to allow. All other categories will be blocked. Cannot be set with `blocked_categories`.
      - `allowed_merchant_countries` string[], nullable — Array of strings containing representing countries from which authorizations will be allowed. Authorizations from merchants in all other countries will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. `US`). Cannot be set with `blocked_merchant_countries`. Provide an empty value to unset this control.
      - `blocked_card_presences` string[], nullable — Array of card presence statuses from which authorizations will be declined. Possible options are `present`, `not_present`. Cannot be set with `allowed_card_presences`. Provide an empty value to unset this control.
      - `blocked_categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) of authorizations to decline. All other categories will be allowed. Cannot be set with `allowed_categories`.
      - `blocked_merchant_countries` string[], nullable — Array of strings containing representing countries from which authorizations will be declined. Country codes should be ISO 3166 alpha-2 country codes (e.g. `US`). Cannot be set with `allowed_merchant_countries`. Provide an empty value to unset this control.
      - `spending_limits` IssuingCardholderSpendingLimit[], nullable — Limit spending with amount-based rules that apply across this cardholder's cards.
        - `amount` integer, required — Maximum amount allowed to spend per interval. This amount is in the card's currency and in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal).
        - `categories` string[], nullable — Array of strings containing [categories](https://docs.stripe.com/api#issuing_authorization_object-merchant_data-category) this limit applies to. Omitting this field will apply the limit to all categories.
        - `interval` 'all_time' | 'daily' | 'monthly' | 'per_authorization' | 'weekly' | 'yearly', required — Interval (or event) to which the amount applies.
      - `spending_limits_currency` string, currency, nullable — Currency of the amounts within `spending_limits`.
    - `status` 'active' | 'blocked' | 'inactive', required — Specifies whether to permit authorizations on this cardholder's cards.
    - `type` 'company' | 'individual', required — One of `individual` or `company`. See [Choose a cardholder type](https://docs.stripe.com/issuing/other/choose-cardholder) for more details.
  - `has_more` boolean, required — True if this list has another page of items after this one that can be fetched.
  - `object` 'list', required — String representing the object's type. Objects of the same type share the same value. Always has the value `list`.
  - `url` string, required — The URL where this list can be accessed.

## Other responses

- `default` — Error response.

---

[API](https://skmtc.net/stripe/apis/stripe-api.md) · [All operations](https://skmtc.net/stripe/apis/stripe-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/stripe/stripe-api/versions/707de00b0616/schema)