API reference
Test mode. Use your secret key on your server; live processing is currently disabled.
https://api.knoxapi.com
Send form-encoded requests with Authorization: Bearer sk_test_....
Complete OpenAPI specification · Integration guide
Operations and schemas are based on the pinned Stripe OpenAPI specification (MIT). Nested object definitions and enums are available in the complete specification.
GET /v1/accounts
List all connected accounts
Returns a list of accounts connected to your platform via Connect. If you’re not a platform, the list is empty.
Request parameters
| Parameter | Location | Type | Description |
|---|
created | query | one of multiple schemas | Only return connected accounts that were created during the given date interval. |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
data required | array of account | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts
Create an account
With Connect, you can create Stripe accounts for your users.
To do this, you’ll first need to register your platform.
If you’ve already collected information for your connected accounts, you can prefill that information when
creating the account. Connect Onboarding won’t ask for the prefilled information during account onboarding.
You can prefill any information on the account.
Request parameters
| Field | Type | Description |
|---|
account_token | string | An [account token](https://api.stripe.com#create_account_token), used to securely provide details to the account. |
bank_account | one of multiple schemas | Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details. |
business_profile | object | Business information about the account. |
business_type | string | The business type. Once you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
capabilities | object | Each key of the dictionary represents a capability, and each capability
maps to its settings (for example, whether it has been requested or not). Each
capability is inactive until you have provided its specific
requirements and Stripe has verified them. An account might have some
of its requested capabilities be active and some be inactive.
Required when [account.controller.stripe_dashboard.type](/api/accounts/create#create_account-controller-dashboard-type)
is `none`, which includes Custom accounts. |
company | object | Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
controller | object | A hash of configuration describing the account controller's attributes. |
country | string | The country in which the account holder resides, or in which the business is legally established. This should be an ISO 3166-1 alpha-2 country code. For example, if you are in the United States and the business for which you're creating an account is legally represented in Canada, you would use `CA` as the country for the account being created. Available countries include [Stripe's global markets](https://stripe.com/global) as well as countries where [cross-border payouts](https://stripe.com/docs/connect/cross-border-payouts) are supported. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://docs.stripe.com/payouts). |
documents | object | Documents that may be submitted to satisfy various informational requests. |
email | string | The email address of the account holder. This is only to make the account easier to identify to you. If [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, Stripe doesn't email the account without your consent. |
expand | array of string | Specifies which fields in the response should be expanded. |
external_account | string | A card or bank account to attach to the account for receiving [payouts](/connect/bank-debit-card-payouts) (you won’t be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](/js), or a dictionary, as documented in the `external_account` parameter for [bank account](/api#account_create_bank_account) creation. By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](/api#account_create_bank_account) or [card creation](/api#account_create_card) APIs. After you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
groups | object | A hash of account group type to tokens. These are account groups this account should be added to. |
individual | object | Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
metadata | one of multiple schemas | 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`. |
settings | object | Options for customizing how the account functions within Stripe. |
tos_acceptance | object | Details on the account's acceptance of the [Stripe Services Agreement](/connect/updating-accounts#tos-acceptance). This property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. This property defaults to a `full` service agreement when empty. |
type | string | The `type` parameter is deprecated. Use [`controller`](/api/accounts/create#create_account-controller) instead to configure dashboard access, fee payer, loss liability, and requirement collection. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
business_profile | one of multiple schemas | Business information about the account. |
business_type | string | The business type. |
capabilities | account_capabilities | |
charges_enabled | boolean | Whether the account can process charges. |
company | legal_entity_company | |
controller | account_unification_account_controller | |
country | string | The account's country. |
created | integer | Time at which the account was connected. Measured in seconds since the Unix epoch. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://stripe.com/docs/payouts). |
details_submitted | boolean | Whether account details have been submitted. Accounts with Stripe Dashboard access, which includes Standard accounts, cannot receive payouts before this is true. Accounts where this is false should be directed to [an onboarding flow](/connect/onboarding) to finish submitting account details. |
email | string | An email address associated with the account. It's not used for authentication and Stripe doesn't market to this field without explicit approval from the platform. |
external_accounts | object | External accounts (bank accounts and debit cards) currently attached to this account. External accounts are only returned for requests where `controller[is_controller]` is true. |
future_requirements | account_future_requirements | |
groups | one of multiple schemas | The groups associated with the account. |
id required | string | Unique identifier for the object. |
individual | person | |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payouts_enabled | boolean | Whether the funds in this account can be paid out. |
requirements | account_requirements | |
settings | one of multiple schemas | Options for customizing how the account functions within Stripe. |
tos_acceptance | account_tos_acceptance | |
type | string | The Stripe account type. Can be `standard`, `express`, `custom`, or `none`. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
DELETE /v1/accounts/{account}
Delete an account
With Connect, you can delete accounts you manage.
Test-mode accounts can be deleted at any time.
Live-mode accounts that have access to the standard dashboard and Stripe is responsible for negative account balances cannot be deleted, which includes Standard accounts. All other Live-mode accounts, can be deleted when all balances are zero.
If you want to delete your own account, use the account information tab in your account settings instead.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
deleted required | boolean | Always true for a deleted object |
id required | string | Unique identifier for the object. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}
Retrieve account
Retrieves the details of an account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
business_profile | one of multiple schemas | Business information about the account. |
business_type | string | The business type. |
capabilities | account_capabilities | |
charges_enabled | boolean | Whether the account can process charges. |
company | legal_entity_company | |
controller | account_unification_account_controller | |
country | string | The account's country. |
created | integer | Time at which the account was connected. Measured in seconds since the Unix epoch. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://stripe.com/docs/payouts). |
details_submitted | boolean | Whether account details have been submitted. Accounts with Stripe Dashboard access, which includes Standard accounts, cannot receive payouts before this is true. Accounts where this is false should be directed to [an onboarding flow](/connect/onboarding) to finish submitting account details. |
email | string | An email address associated with the account. It's not used for authentication and Stripe doesn't market to this field without explicit approval from the platform. |
external_accounts | object | External accounts (bank accounts and debit cards) currently attached to this account. External accounts are only returned for requests where `controller[is_controller]` is true. |
future_requirements | account_future_requirements | |
groups | one of multiple schemas | The groups associated with the account. |
id required | string | Unique identifier for the object. |
individual | person | |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payouts_enabled | boolean | Whether the funds in this account can be paid out. |
requirements | account_requirements | |
settings | one of multiple schemas | Options for customizing how the account functions within Stripe. |
tos_acceptance | account_tos_acceptance | |
type | string | The Stripe account type. Can be `standard`, `express`, `custom`, or `none`. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}
Update an account
Updates a connected account by setting the values of the parameters passed. Any parameters not provided are
left unchanged.
For accounts where controller.requirement_collection
is application, which includes Custom accounts, you can update any information on the account.
For accounts where controller.requirement_collection
is stripe, which includes Standard and Express accounts, you can update all information until you create
an Account Link or Account Session to start Connect onboarding,
after which some properties can no longer be updated.
To update your own account, use the Dashboard. Refer to our
Connect documentation to learn more about updating accounts.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
account_token | string | An [account token](https://api.stripe.com#create_account_token), used to securely provide details to the account. |
business_profile | object | Business information about the account. |
business_type | string | The business type. Once you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
capabilities | object | Each key of the dictionary represents a capability, and each capability
maps to its settings (for example, whether it has been requested or not). Each
capability is inactive until you have provided its specific
requirements and Stripe has verified them. An account might have some
of its requested capabilities be active and some be inactive.
Required when [account.controller.stripe_dashboard.type](/api/accounts/create#create_account-controller-dashboard-type)
is `none`, which includes Custom accounts. |
company | object | Information about the company or business. This field is available for any `business_type`. Once you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://docs.stripe.com/payouts). |
documents | object | Documents that may be submitted to satisfy various informational requests. |
email | string | The email address of the account holder. This is only to make the account easier to identify to you. If [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts, Stripe doesn't email the account without your consent. |
expand | array of string | Specifies which fields in the response should be expanded. |
external_account | string | A card or bank account to attach to the account for receiving [payouts](/connect/bank-debit-card-payouts) (you won’t be able to use it for top-ups). You can provide either a token, like the ones returned by [Stripe.js](/js), or a dictionary, as documented in the `external_account` parameter for [bank account](/api#account_create_bank_account) creation. By default, providing an external account sets it as the new default external account for its currency, and deletes the old default if one exists. To add additional external accounts without replacing the existing default for the currency, use the [bank account](/api#account_create_bank_account) or [card creation](/api#account_create_card) APIs. After you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
groups | object | A hash of account group type to tokens. These are account groups this account should be added to. |
individual | object | Information about the person represented by the account. This field is null unless `business_type` is set to `individual`. Once you create an [Account Link](/api/account_links) or [Account Session](/api/account_sessions), this property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. |
metadata | one of multiple schemas | 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`. |
settings | object | Options for customizing how the account functions within Stripe. |
tos_acceptance | object | Details on the account's acceptance of the [Stripe Services Agreement](/connect/updating-accounts#tos-acceptance). This property can only be updated for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `application`, which includes Custom accounts. This property defaults to a `full` service agreement when empty. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
business_profile | one of multiple schemas | Business information about the account. |
business_type | string | The business type. |
capabilities | account_capabilities | |
charges_enabled | boolean | Whether the account can process charges. |
company | legal_entity_company | |
controller | account_unification_account_controller | |
country | string | The account's country. |
created | integer | Time at which the account was connected. Measured in seconds since the Unix epoch. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://stripe.com/docs/payouts). |
details_submitted | boolean | Whether account details have been submitted. Accounts with Stripe Dashboard access, which includes Standard accounts, cannot receive payouts before this is true. Accounts where this is false should be directed to [an onboarding flow](/connect/onboarding) to finish submitting account details. |
email | string | An email address associated with the account. It's not used for authentication and Stripe doesn't market to this field without explicit approval from the platform. |
external_accounts | object | External accounts (bank accounts and debit cards) currently attached to this account. External accounts are only returned for requests where `controller[is_controller]` is true. |
future_requirements | account_future_requirements | |
groups | one of multiple schemas | The groups associated with the account. |
id required | string | Unique identifier for the object. |
individual | person | |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payouts_enabled | boolean | Whether the funds in this account can be paid out. |
requirements | account_requirements | |
settings | one of multiple schemas | Options for customizing how the account functions within Stripe. |
tos_acceptance | account_tos_acceptance | |
type | string | The Stripe account type. Can be `standard`, `express`, `custom`, or `none`. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/bank_accounts
Create an external account
Create an external account for a given account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
bank_account | one of multiple schemas | Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details. |
default_for_currency | boolean | When set to true, or if this is the first external account added in this currency, this account becomes the default external account for its currency. |
expand | array of string | Specifies which fields in the response should be expanded. |
external_account | string | A token, like the ones returned by [Stripe.js](https://docs.stripe.com/js) or a dictionary containing a user's external account details (with the options shown below). Please refer to full [documentation](https://stripe.com/docs/api/external_accounts) instead. |
metadata | object | 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`. |
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/capabilities
List all account capabilities
Returns a list of capabilities associated with the account. The capabilities are returned sorted by creation date, with the most recent capability appearing first.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
data required | array of capability | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/external_accounts
List all external accounts
List external accounts for an account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
object | query | string | Filter external accounts according to a particular object type. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
data required | array of one of multiple schemas | The list contains all external accounts that have been attached to the Stripe account. These may be bank accounts or cards. |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/external_accounts
Create an external account
Create an external account for a given account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
bank_account | one of multiple schemas | Either a token, like the ones returned by [Stripe.js](https://stripe.com/docs/js), or a dictionary containing a user's bank account details. |
default_for_currency | boolean | When set to true, or if this is the first external account added in this currency, this account becomes the default external account for its currency. |
expand | array of string | Specifies which fields in the response should be expanded. |
external_account | string | A token, like the ones returned by [Stripe.js](https://docs.stripe.com/js) or a dictionary containing a user's external account details (with the options shown below). Please refer to full [documentation](https://stripe.com/docs/api/external_accounts) instead. |
metadata | object | 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`. |
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/login_links
Create a login link
Creates a login link for a connected account to access the Express Dashboard.
You can only create login links for accounts that use the Express Dashboard and are connected to your platform.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
expand | array of string | Specifies which fields in the response should be expanded. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
url required | string | The URL for the login link. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/people
List all persons
Returns a list of people associated with the account’s legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
relationship | query | object | Filters on the list of people returned based on the person's relationship to the account's company. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
data required | array of person | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/people
Create a person
Creates a new person.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
additional_tos_acceptances | object | Details on the legal guardian's or authorizer's acceptance of the required Stripe agreements. |
address | object | The person's address. |
address_kana | object | The Kana variation of the person's address (Japan only). |
address_kanji | object | The Kanji variation of the person's address (Japan only). |
dob | one of multiple schemas | The person's date of birth. |
documents | object | Documents that may be submitted to satisfy various informational requests. |
email | string | The person's email address. |
expand | array of string | Specifies which fields in the response should be expanded. |
first_name | string | The person's first name. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). |
full_name_aliases | one of multiple schemas | A list of alternate names or aliases that the person is known by. |
gender | string | The person's gender (International regulations require either "male" or "female"). |
id_number | string | The person's ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
id_number_secondary | string | The person's secondary ID number, as appropriate for their country, will be used for enhanced verification checks. In Thailand, this would be the laser code found on the back of an ID card. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
last_name | string | The person's last name. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). |
maiden_name | string | The person's maiden name. |
metadata | one of multiple schemas | 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`. |
nationality | string | The country where the person is a national. Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), or "XX" if unavailable. |
person_token | string | A [person token](https://docs.stripe.com/connect/account-tokens), used to securely provide details to the person. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | object | The person's registered address. |
relationship | object | The relationship that this person has with the account's legal entity. |
ssn_last_4 | string | The last four digits of the person's Social Security number (U.S. only).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
us_cfpb_data | object | Demographic data related to the person. |
verification | object | The person's verification status. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | string | The account the person is associated with. |
additional_tos_acceptances | person_additional_tos_acceptances | |
address | address | |
address_kana | one of multiple schemas | |
address_kanji | one of multiple schemas | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
dob | legal_entity_dob | |
email | string | The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name | string | The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
full_name_aliases | array of string | A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
future_requirements | one of multiple schemas | |
gender | string | The person's gender. |
id required | string | Unique identifier for the object. |
id_number_provided | boolean | Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`). |
id_number_secondary_provided | boolean | Whether the person's `id_number_secondary` was provided. |
last_name | string | The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
maiden_name | string | The person's maiden name. |
metadata | object | 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. |
nationality | string | The country where the person is a national. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | address | |
relationship | person_relationship | |
requirements | one of multiple schemas | |
ssn_last_4_provided | boolean | Whether the last four digits of the person's Social Security number have been provided (U.S. only). |
us_cfpb_data | one of multiple schemas | Demographic data related to the person. |
verification | legal_entity_person_verification | |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/persons
List all persons
Returns a list of people associated with the account’s legal entity. The people are returned sorted by creation date, with the most recent people appearing first.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
ending_before | query | string | A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list. |
expand | query | array of string | Specifies which fields in the response should be expanded. |
limit | query | integer | A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10. |
relationship | query | object | Filters on the list of people returned based on the person's relationship to the account's company. |
starting_after | query | string | A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
data required | array of person | |
has_more required | boolean | True if this list has another page of items after this one that can be fetched. |
object required | string | String representing the object's type. Objects of the same type share the same value. Always has the value `list`. |
url required | string | The URL where this list can be accessed. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/persons
Create a person
Creates a new person.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
additional_tos_acceptances | object | Details on the legal guardian's or authorizer's acceptance of the required Stripe agreements. |
address | object | The person's address. |
address_kana | object | The Kana variation of the person's address (Japan only). |
address_kanji | object | The Kanji variation of the person's address (Japan only). |
dob | one of multiple schemas | The person's date of birth. |
documents | object | Documents that may be submitted to satisfy various informational requests. |
email | string | The person's email address. |
expand | array of string | Specifies which fields in the response should be expanded. |
first_name | string | The person's first name. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). |
full_name_aliases | one of multiple schemas | A list of alternate names or aliases that the person is known by. |
gender | string | The person's gender (International regulations require either "male" or "female"). |
id_number | string | The person's ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
id_number_secondary | string | The person's secondary ID number, as appropriate for their country, will be used for enhanced verification checks. In Thailand, this would be the laser code found on the back of an ID card. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
last_name | string | The person's last name. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). |
maiden_name | string | The person's maiden name. |
metadata | one of multiple schemas | 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`. |
nationality | string | The country where the person is a national. Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), or "XX" if unavailable. |
person_token | string | A [person token](https://docs.stripe.com/connect/account-tokens), used to securely provide details to the person. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | object | The person's registered address. |
relationship | object | The relationship that this person has with the account's legal entity. |
ssn_last_4 | string | The last four digits of the person's Social Security number (U.S. only).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
us_cfpb_data | object | Demographic data related to the person. |
verification | object | The person's verification status. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | string | The account the person is associated with. |
additional_tos_acceptances | person_additional_tos_acceptances | |
address | address | |
address_kana | one of multiple schemas | |
address_kanji | one of multiple schemas | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
dob | legal_entity_dob | |
email | string | The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name | string | The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
full_name_aliases | array of string | A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
future_requirements | one of multiple schemas | |
gender | string | The person's gender. |
id required | string | Unique identifier for the object. |
id_number_provided | boolean | Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`). |
id_number_secondary_provided | boolean | Whether the person's `id_number_secondary` was provided. |
last_name | string | The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
maiden_name | string | The person's maiden name. |
metadata | object | 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. |
nationality | string | The country where the person is a national. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | address | |
relationship | person_relationship | |
requirements | one of multiple schemas | |
ssn_last_4_provided | boolean | Whether the last four digits of the person's Social Security number have been provided (U.S. only). |
us_cfpb_data | one of multiple schemas | Demographic data related to the person. |
verification | legal_entity_person_verification | |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/reject
Reject an account
With Connect, you can reject accounts that you have flagged as suspicious.
Only accounts where your platform is liable for negative account balances, which includes Custom and Express accounts, can be rejected.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
expand | array of string | Specifies which fields in the response should be expanded. |
payouts_action | string | Whether to pause payouts on the account as part of the rejection. Defaults to `pause`. Use `none` to leave payouts enabled. |
reason required | string | The reason for rejecting the account. Can be `fraud`, `terms_of_service`, or `other`. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
business_profile | one of multiple schemas | Business information about the account. |
business_type | string | The business type. |
capabilities | account_capabilities | |
charges_enabled | boolean | Whether the account can process charges. |
company | legal_entity_company | |
controller | account_unification_account_controller | |
country | string | The account's country. |
created | integer | Time at which the account was connected. Measured in seconds since the Unix epoch. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://stripe.com/docs/payouts). |
details_submitted | boolean | Whether account details have been submitted. Accounts with Stripe Dashboard access, which includes Standard accounts, cannot receive payouts before this is true. Accounts where this is false should be directed to [an onboarding flow](/connect/onboarding) to finish submitting account details. |
email | string | An email address associated with the account. It's not used for authentication and Stripe doesn't market to this field without explicit approval from the platform. |
external_accounts | object | External accounts (bank accounts and debit cards) currently attached to this account. External accounts are only returned for requests where `controller[is_controller]` is true. |
future_requirements | account_future_requirements | |
groups | one of multiple schemas | The groups associated with the account. |
id required | string | Unique identifier for the object. |
individual | person | |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payouts_enabled | boolean | Whether the funds in this account can be paid out. |
requirements | account_requirements | |
settings | one of multiple schemas | Options for customizing how the account functions within Stripe. |
tos_acceptance | account_tos_acceptance | |
type | string | The Stripe account type. Can be `standard`, `express`, `custom`, or `none`. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/unreject
Unreject an account
With Connect, you can unreject accounts that you have previously rejected.
Only accounts that were rejected by your platform can be unrejected. This API cannot be used to unreject accounts that were rejected by Stripe.
Unreject will only enable charges and/or payouts if there are no other restrictions other than those placed by a previous rejection. If you have separately paused charges and/or payouts outside of rejection, those pauses will remain in place after unrejection.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
| Field | Type | Description |
|---|
expand | array of string | Specifies which fields in the response should be expanded. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
business_profile | one of multiple schemas | Business information about the account. |
business_type | string | The business type. |
capabilities | account_capabilities | |
charges_enabled | boolean | Whether the account can process charges. |
company | legal_entity_company | |
controller | account_unification_account_controller | |
country | string | The account's country. |
created | integer | Time at which the account was connected. Measured in seconds since the Unix epoch. |
default_currency | string | Three-letter ISO currency code representing the default currency for the account. This must be a currency that [Stripe supports in the account's country](https://stripe.com/docs/payouts). |
details_submitted | boolean | Whether account details have been submitted. Accounts with Stripe Dashboard access, which includes Standard accounts, cannot receive payouts before this is true. Accounts where this is false should be directed to [an onboarding flow](/connect/onboarding) to finish submitting account details. |
email | string | An email address associated with the account. It's not used for authentication and Stripe doesn't market to this field without explicit approval from the platform. |
external_accounts | object | External accounts (bank accounts and debit cards) currently attached to this account. External accounts are only returned for requests where `controller[is_controller]` is true. |
future_requirements | account_future_requirements | |
groups | one of multiple schemas | The groups associated with the account. |
id required | string | Unique identifier for the object. |
individual | person | |
metadata | object | 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. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
payouts_enabled | boolean | Whether the funds in this account can be paid out. |
requirements | account_requirements | |
settings | one of multiple schemas | Options for customizing how the account functions within Stripe. |
tos_acceptance | account_tos_acceptance | |
type | string | The Stripe account type. Can be `standard`, `express`, `custom`, or `none`. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
DELETE /v1/accounts/{account}/bank_accounts/{id}
Delete an external account
Delete a specified external account for a given account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
id | path | string | Unique identifier for the external account to be deleted. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/bank_accounts/{id}
Retrieve an external account
Retrieve a specified external account for a given account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
id | path | string | Unique identifier for the external account to be retrieved. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/bank_accounts/{id}
Update a bank account
Updates the metadata, account holder name, account holder type of a bank account belonging to
a connected account and optionally sets it as the default for its currency. Other bank account
details are not editable by design.
You can only update bank accounts when account.controller.requirement_collection is application, which includes Custom accounts.
You can re-enable a disabled bank account by performing an update call without providing any
arguments or changes.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
id | path | string | |
| Field | Type | Description |
|---|
account_holder_name | string | The name of the person or business that owns the bank account. |
account_holder_type | string | The type of entity that holds the account. This can be either `individual` or `company`. |
account_type | string | The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`. |
address_city | string | City/District/Suburb/Town/Village. |
address_country | string | Billing address country, if provided when creating card. |
address_line1 | string | Address line 1 (Street address/PO Box/Company name). |
address_line2 | string | Address line 2 (Apartment/Suite/Unit/Building). |
address_state | string | State/County/Province/Region. |
address_zip | string | ZIP or postal code. |
default_for_currency | boolean | When set to true, this becomes the default external account for its currency. |
documents | object | Documents that may be submitted to satisfy various informational requests. |
exp_month | string | Two digit number representing the card’s expiration month. |
exp_year | string | Four digit number representing the card’s expiration year. |
expand | array of string | Specifies which fields in the response should be expanded. |
metadata | one of multiple schemas | 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`. |
name | string | Cardholder name. |
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/capabilities/{capability}
Retrieve an Account Capability
Retrieves information about the specified Account Capability.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
capability | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | one of multiple schemas | The account for which the capability enables functionality. |
future_requirements | account_capability_future_requirements | |
id required | string | The identifier for the capability. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
requested required | boolean | Whether the capability has been requested. |
requested_at | integer | Time at which the capability was requested. Measured in seconds since the Unix epoch. |
requirements | account_capability_requirements | |
status required | string | The status of the capability. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/capabilities/{capability}
Update an Account Capability
Updates an existing Account Capability. Request or remove a capability by updating its requested parameter.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
capability | path | string | |
| Field | Type | Description |
|---|
expand | array of string | Specifies which fields in the response should be expanded. |
requested | boolean | To request a new capability for an account, pass true. There can be a delay before the requested capability becomes active. If the capability has any activation requirements, the response includes them in the `requirements` arrays.
If a capability isn't permanent, you can remove it from the account by passing false. Some capabilities are permanent after they've been requested. Attempting to remove a permanent capability returns an error. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | one of multiple schemas | The account for which the capability enables functionality. |
future_requirements | account_capability_future_requirements | |
id required | string | The identifier for the capability. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
requested required | boolean | Whether the capability has been requested. |
requested_at | integer | Time at which the capability was requested. Measured in seconds since the Unix epoch. |
requirements | account_capability_requirements | |
status required | string | The status of the capability. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
DELETE /v1/accounts/{account}/external_accounts/{id}
Delete an external account
Delete a specified external account for a given account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
id | path | string | Unique identifier for the external account to be deleted. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/external_accounts/{id}
Retrieve an external account
Retrieve a specified external account for a given account.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
id | path | string | Unique identifier for the external account to be retrieved. |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/external_accounts/{id}
Update a bank account
Updates the metadata, account holder name, account holder type of a bank account belonging to
a connected account and optionally sets it as the default for its currency. Other bank account
details are not editable by design.
You can only update bank accounts when account.controller.requirement_collection is application, which includes Custom accounts.
You can re-enable a disabled bank account by performing an update call without providing any
arguments or changes.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
id | path | string | |
| Field | Type | Description |
|---|
account_holder_name | string | The name of the person or business that owns the bank account. |
account_holder_type | string | The type of entity that holds the account. This can be either `individual` or `company`. |
account_type | string | The bank account type. This can only be `checking` or `savings` in most countries. In Japan, this can only be `futsu` or `toza`. |
address_city | string | City/District/Suburb/Town/Village. |
address_country | string | Billing address country, if provided when creating card. |
address_line1 | string | Address line 1 (Street address/PO Box/Company name). |
address_line2 | string | Address line 2 (Apartment/Suite/Unit/Building). |
address_state | string | State/County/Province/Region. |
address_zip | string | ZIP or postal code. |
default_for_currency | boolean | When set to true, this becomes the default external account for its currency. |
documents | object | Documents that may be submitted to satisfy various informational requests. |
exp_month | string | Two digit number representing the card’s expiration month. |
exp_year | string | Four digit number representing the card’s expiration year. |
expand | array of string | Specifies which fields in the response should be expanded. |
metadata | one of multiple schemas | 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`. |
name | string | Cardholder name. |
Responses
HTTP 200: Successful response.
one of multiple schemas. See the OpenAPI specification for the complete schema.
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
DELETE /v1/accounts/{account}/people/{person}
Delete a person
Deletes an existing person’s relationship to the account’s legal entity. Any person with a relationship for an account can be deleted through the API, except if the person is the representative. If your integration is using the executive parameter, you cannot delete the only verified executive on file.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
person | path | string | |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
deleted required | boolean | Always true for a deleted object |
id required | string | Unique identifier for the object. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/people/{person}
Retrieve a person
Retrieves an existing person.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
person | path | string | |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | string | The account the person is associated with. |
additional_tos_acceptances | person_additional_tos_acceptances | |
address | address | |
address_kana | one of multiple schemas | |
address_kanji | one of multiple schemas | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
dob | legal_entity_dob | |
email | string | The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name | string | The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
full_name_aliases | array of string | A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
future_requirements | one of multiple schemas | |
gender | string | The person's gender. |
id required | string | Unique identifier for the object. |
id_number_provided | boolean | Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`). |
id_number_secondary_provided | boolean | Whether the person's `id_number_secondary` was provided. |
last_name | string | The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
maiden_name | string | The person's maiden name. |
metadata | object | 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. |
nationality | string | The country where the person is a national. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | address | |
relationship | person_relationship | |
requirements | one of multiple schemas | |
ssn_last_4_provided | boolean | Whether the last four digits of the person's Social Security number have been provided (U.S. only). |
us_cfpb_data | one of multiple schemas | Demographic data related to the person. |
verification | legal_entity_person_verification | |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/people/{person}
Update a person
Updates an existing person.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
person | path | string | |
| Field | Type | Description |
|---|
additional_tos_acceptances | object | Details on the legal guardian's or authorizer's acceptance of the required Stripe agreements. |
address | object | The person's address. |
address_kana | object | The Kana variation of the person's address (Japan only). |
address_kanji | object | The Kanji variation of the person's address (Japan only). |
dob | one of multiple schemas | The person's date of birth. |
documents | object | Documents that may be submitted to satisfy various informational requests. |
email | string | The person's email address. |
expand | array of string | Specifies which fields in the response should be expanded. |
first_name | string | The person's first name. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). |
full_name_aliases | one of multiple schemas | A list of alternate names or aliases that the person is known by. |
gender | string | The person's gender (International regulations require either "male" or "female"). |
id_number | string | The person's ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
id_number_secondary | string | The person's secondary ID number, as appropriate for their country, will be used for enhanced verification checks. In Thailand, this would be the laser code found on the back of an ID card. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
last_name | string | The person's last name. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). |
maiden_name | string | The person's maiden name. |
metadata | one of multiple schemas | 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`. |
nationality | string | The country where the person is a national. Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), or "XX" if unavailable. |
person_token | string | A [person token](https://docs.stripe.com/connect/account-tokens), used to securely provide details to the person. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | object | The person's registered address. |
relationship | object | The relationship that this person has with the account's legal entity. |
ssn_last_4 | string | The last four digits of the person's Social Security number (U.S. only).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
us_cfpb_data | object | Demographic data related to the person. |
verification | object | The person's verification status. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | string | The account the person is associated with. |
additional_tos_acceptances | person_additional_tos_acceptances | |
address | address | |
address_kana | one of multiple schemas | |
address_kanji | one of multiple schemas | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
dob | legal_entity_dob | |
email | string | The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name | string | The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
full_name_aliases | array of string | A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
future_requirements | one of multiple schemas | |
gender | string | The person's gender. |
id required | string | Unique identifier for the object. |
id_number_provided | boolean | Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`). |
id_number_secondary_provided | boolean | Whether the person's `id_number_secondary` was provided. |
last_name | string | The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
maiden_name | string | The person's maiden name. |
metadata | object | 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. |
nationality | string | The country where the person is a national. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | address | |
relationship | person_relationship | |
requirements | one of multiple schemas | |
ssn_last_4_provided | boolean | Whether the last four digits of the person's Social Security number have been provided (U.S. only). |
us_cfpb_data | one of multiple schemas | Demographic data related to the person. |
verification | legal_entity_person_verification | |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
DELETE /v1/accounts/{account}/persons/{person}
Delete a person
Deletes an existing person’s relationship to the account’s legal entity. Any person with a relationship for an account can be deleted through the API, except if the person is the representative. If your integration is using the executive parameter, you cannot delete the only verified executive on file.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
person | path | string | |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
deleted required | boolean | Always true for a deleted object |
id required | string | Unique identifier for the object. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
GET /v1/accounts/{account}/persons/{person}
Retrieve a person
Retrieves an existing person.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
expand | query | array of string | Specifies which fields in the response should be expanded. |
person | path | string | |
object. See the OpenAPI specification for the complete schema.
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | string | The account the person is associated with. |
additional_tos_acceptances | person_additional_tos_acceptances | |
address | address | |
address_kana | one of multiple schemas | |
address_kanji | one of multiple schemas | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
dob | legal_entity_dob | |
email | string | The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name | string | The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
full_name_aliases | array of string | A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
future_requirements | one of multiple schemas | |
gender | string | The person's gender. |
id required | string | Unique identifier for the object. |
id_number_provided | boolean | Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`). |
id_number_secondary_provided | boolean | Whether the person's `id_number_secondary` was provided. |
last_name | string | The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
maiden_name | string | The person's maiden name. |
metadata | object | 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. |
nationality | string | The country where the person is a national. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | address | |
relationship | person_relationship | |
requirements | one of multiple schemas | |
ssn_last_4_provided | boolean | Whether the last four digits of the person's Social Security number have been provided (U.S. only). |
us_cfpb_data | one of multiple schemas | Demographic data related to the person. |
verification | legal_entity_person_verification | |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |
POST /v1/accounts/{account}/persons/{person}
Update a person
Updates an existing person.
Request parameters
| Parameter | Location | Type | Description |
|---|
account | path | string | |
person | path | string | |
| Field | Type | Description |
|---|
additional_tos_acceptances | object | Details on the legal guardian's or authorizer's acceptance of the required Stripe agreements. |
address | object | The person's address. |
address_kana | object | The Kana variation of the person's address (Japan only). |
address_kanji | object | The Kanji variation of the person's address (Japan only). |
dob | one of multiple schemas | The person's date of birth. |
documents | object | Documents that may be submitted to satisfy various informational requests. |
email | string | The person's email address. |
expand | array of string | Specifies which fields in the response should be expanded. |
first_name | string | The person's first name. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). |
full_name_aliases | one of multiple schemas | A list of alternate names or aliases that the person is known by. |
gender | string | The person's gender (International regulations require either "male" or "female"). |
id_number | string | The person's ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
id_number_secondary | string | The person's secondary ID number, as appropriate for their country, will be used for enhanced verification checks. In Thailand, this would be the laser code found on the back of an ID card. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
last_name | string | The person's last name. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). |
maiden_name | string | The person's maiden name. |
metadata | one of multiple schemas | 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`. |
nationality | string | The country where the person is a national. Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), or "XX" if unavailable. |
person_token | string | A [person token](https://docs.stripe.com/connect/account-tokens), used to securely provide details to the person. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | object | The person's registered address. |
relationship | object | The relationship that this person has with the account's legal entity. |
ssn_last_4 | string | The last four digits of the person's Social Security number (U.S. only).
Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance). |
us_cfpb_data | object | Demographic data related to the person. |
verification | object | The person's verification status. |
Responses
HTTP 200: Successful response.
| Field | Type | Description |
|---|
account required | string | The account the person is associated with. |
additional_tos_acceptances | person_additional_tos_acceptances | |
address | address | |
address_kana | one of multiple schemas | |
address_kanji | one of multiple schemas | |
created required | integer | Time at which the object was created. Measured in seconds since the Unix epoch. |
dob | legal_entity_dob | |
email | string | The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name | string | The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kana | string | The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
first_name_kanji | string | The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
full_name_aliases | array of string | A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
future_requirements | one of multiple schemas | |
gender | string | The person's gender. |
id required | string | Unique identifier for the object. |
id_number_provided | boolean | Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`). |
id_number_secondary_provided | boolean | Whether the person's `id_number_secondary` was provided. |
last_name | string | The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kana | string | The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
last_name_kanji | string | The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`. |
maiden_name | string | The person's maiden name. |
metadata | object | 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. |
nationality | string | The country where the person is a national. |
object required | string | String representing the object's type. Objects of the same type share the same value. |
phone | string | The person's phone number. |
political_exposure | string | Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction. |
registered_address | address | |
relationship | person_relationship | |
requirements | one of multiple schemas | |
ssn_last_4_provided | boolean | Whether the last four digits of the person's Social Security number have been provided (U.S. only). |
us_cfpb_data | one of multiple schemas | Demographic data related to the person. |
verification | legal_entity_person_verification | |
HTTP default: Error response.
| Field | Type | Description |
|---|
error required | api_errors | |