Sample - Stripe API
POST/v1/issuing/cardholders

Create a cardholder

Creates a new Issuing Cardholder object that can be issued cards.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

12 body fields
billingobjectrequired
The cardholder's billing address.
companyobjectoptional
Additional information about a `company` cardholder.
emailstringoptional
The cardholder's email address.
expandarray<string>optional
Specifies which fields in the response should be expanded.
individualobjectoptional
Additional information about an `individual` cardholder.
metadataobjectoptional
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
namestringrequired
The cardholder's name. This will be printed on cards issued to them. The maximum length of this field is 24 characters. This field cannot contain any special characters or numbers.
phone_numberstringoptional
The cardholder's phone number. This will be transformed to [E.164](https://en.wikipedia.org/wiki/E.164) if it is not provided in that format already. 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_localesarray<string>optional
The cardholder’s preferred locales (languages), ordered by preference. Locales can be `de`, `en`, `es`, `fr`, or `it`. 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.
spending_controlsobjectoptional
Rules that control spending across this cardholder's cards. Refer to our [documentation](https://docs.stripe.com/issuing/controls/spending-controls) for more details.
statusstringoptional
Specifies whether to permit authorizations on this cardholder's cards. Defaults to `active`.
Allowed:activeinactive
typestringoptional
One of `individual` or `company`. See [Choose a cardholder type](https://docs.stripe.com/issuing/other/choose-cardholder) for more details.
Allowed:companyindividual

2 status codes
200Successful response.
billingobjectrequired
companyobjectoptional
Additional information about a `company` cardholder.
createdintegerrequired
Time at which the object was created. Measured in seconds since the Unix epoch.
emailstringoptional
The cardholder's email address.
idstringrequired
Unique identifier for the object.
individualobjectoptional
Additional information about an `individual` cardholder.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadataobjectrequired
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.
namestringrequired
The cardholder's name. This will be printed on cards issued to them.
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:issuing.cardholder
phone_numberstringoptional
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_localesarray<string>optional
The cardholder’s preferred locales (languages), ordered by preference. Locales can be `de`, `en`, `es`, `fr`, or `it`. 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.
requirementsobjectrequired
spending_controlsobjectoptional
Rules that control spending across this cardholder's cards. Refer to our [documentation](https://docs.stripe.com/issuing/controls/spending-controls) for more details.
statusstringrequired
Specifies whether to permit authorizations on this cardholder's cards.
Allowed:activeblockedinactive
typestringrequired
One of `individual` or `company`. See [Choose a cardholder type](https://docs.stripe.com/issuing/other/choose-cardholder) for more details.
Allowed:companyindividual
defaultError response.
errorobjectrequired

Error handling

Any other status is an error: Error response.