Create a Person Token v2

Core Resources

Person Tokens

Create a Person Token

Creates a Person Token associated with an Account.

Learn more about calling API v2 endpoints.

Parameters

account_idstringRequired
The Account the Person is associated with.

additional_addressesarray of objects
Additional addresses associated with the person.
- additional_addresses.citystring
  City, district, suburb, town, or village.
- additional_addresses.countryenum
  Two-letter country code (ISO 3166-1 alpha-2).
- additional_addresses.line1string
  Address line 1 (e.g., street, PO Box, or company name).
- additional_addresses.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
- additional_addresses.postal_codestring
  ZIP or postal code.
- additional_addresses.purposeenumRequired
  Purpose of additional address.
  Possible enum values
  registered
  Registered.
- additional_addresses.statestring
  State, county, province, or region.
- additional_addresses.townstring
  Town or cho-me.

additional_namesarray of objects
Additional names (e.g. aliases) associated with the person.
- additional_names.full_namestring
  The person’s full name.
- additional_names.given_namestring
  The person’s first or given name.
- additional_names.purposeenumRequired
  The purpose or type of the additional name.
  Possible enum values
  alias
  An alias for the individual’s name.
  maiden
  The maiden name of the individual.
- additional_names.surnamestring
  The person’s last or family name.

additional_terms_of_serviceobject
Attestations of accepted terms of service agreements.
- additional_terms_of_service.accountobject
  Details on the Person’s acceptance of the [Stripe Services Agreement]; IP, date, and User Agent are expanded by Stripe.
  additional_terms_of_service.account.shown_and_acceptedboolean
  The boolean value indicating if the terms of service have been accepted.

addressobject
The person’s residential address.
- address.citystring
  City, district, suburb, town, or village.
- address.countryenum
  Two-letter country code (ISO 3166-1 alpha-2).
- address.line1string
  Address line 1 (e.g., street, PO Box, or company name).
- address.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
- address.postal_codestring
  ZIP or postal code.
- address.statestring
  State, county, province, or region.
- address.townstring
  Town or cho-me.

date_of_birthobject
The person’s date of birth.
- date_of_birth.dayintegerRequired
  The day of the birth.
- date_of_birth.monthintegerRequired
  The month of birth.
- date_of_birth.yearintegerRequired
  The year of birth.

documentsobject
Documents that may be submitted to satisfy various informational requests.
- documents.company_authorizationobject
  One or more documents that demonstrate proof that this person is authorized to represent the company.
  documents.company_authorization.filesarray of stringsRequired
  One or more document IDs returned by a file upload with a purpose value of account_requirement.
  documents.company_authorization.typeenumRequired
  The format of the document. Currently supports files only.
  Possible enum values
  files
  Document type with multiple files.
- documents.passportobject
  One or more documents showing the person’s passport page with photo and personal data.
  documents.passport.filesarray of stringsRequired
  One or more document IDs returned by a file upload with a purpose value of account_requirement.
  documents.passport.typeenumRequired
  The format of the document. Currently supports files only.
  Possible enum values
  files
  Document type with multiple files.
- documents.primary_verificationobject
  An identifying document showing the person’s name, either a passport or local ID card.
  documents.primary_verification.front_backobjectRequired
  The file upload tokens referring to each side of the document.
  documents.primary_verification.front_back.backstring
  A file upload token representing the back of the verification document. The purpose of the uploaded file should be ‘identity_document’. The uploaded file needs to be a color image (smaller than 8,000px by 8,000px), in JPG, PNG, or PDF format, and less than 10 MB in size.
  documents.primary_verification.front_back.frontstring
  A file upload token representing the front of the verification document. The purpose of the uploaded file should be ‘identity_document’. The uploaded file needs to be a color image (smaller than 8,000px by 8,000px), in JPG, PNG, or PDF format, and less than 10 MB in size.
  documents.primary_verification.typeenumRequired
  The format of the verification document. Currently supports front_back only.
  Possible enum values
  front_back
  Document type with both front and back sides.
- documents.secondary_verificationobject
  A document showing address, either a passport, local ID card, or utility bill from a well-known utility company.
  documents.secondary_verification.front_backobjectRequired
  The file upload tokens referring to each side of the document.
  documents.secondary_verification.front_back.backstring
  A file upload token representing the back of the verification document. The purpose of the uploaded file should be ‘identity_document’. The uploaded file needs to be a color image (smaller than 8,000px by 8,000px), in JPG, PNG, or PDF format, and less than 10 MB in size.
  documents.secondary_verification.front_back.frontstring
  A file upload token representing the front of the verification document. The purpose of the uploaded file should be ‘identity_document’. The uploaded file needs to be a color image (smaller than 8,000px by 8,000px), in JPG, PNG, or PDF format, and less than 10 MB in size.
  documents.secondary_verification.typeenumRequired
  The format of the verification document. Currently supports front_back only.
  Possible enum values
  front_back
  Document type with both front and back sides.
- documents.visaobject
  One or more documents showing the person’s visa required for living in the country where they are residing.
  documents.visa.filesarray of stringsRequired
  One or more document IDs returned by a file upload with a purpose value of account_requirement.
  documents.visa.typeenumRequired
  The format of the document. Currently supports files only.
  Possible enum values
  files
  Document type with multiple files.

emailstring
Email.

given_namestring
The person’s first name.

id_numbersarray of objects

The identification numbers (e.g., SSN) associated with the person.

id_numbers.typeenumRequired

The ID number type of an individual.

Possible enum values

ae_eid

Emirates ID - United Arab Emirates.

ao_nif

Número de Identificação Fiscal (Tax Identification Number) - Angola.

ar_dni

Documento Nacional de Identidad (DNI) - Argentina.

az_tin

Tax Identification Number - Azerbaijan.

bd_brc

Birth Registration Certificate (BRC) - Bangladesh.

bd_etin

Electronic Tax Identification Number (ETIN) - Bangladesh.

bd_nid

National Identification Number (NID) - Bangladesh.

br_cpf

Cadastro de Pessoas Físicas - Brazil.

cr_cpf

Cédula de Persona Fisica (CPF) - Costa Rica.

cr_dimex

Documento de identificación Tributario Especial (DIMEX) - Costa Rica.

Show 22 more

id_numbers.valuestringRequired
The value of the ID number.

legal_genderenum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

nationalitiesarray of enums
The nationalities (countries) this person is associated with.

phonestring
The phone number for this person.

political_exposureenum
The person’s political exposure.
Possible enum values
existing
The person has disclosed that they do have political exposure.
none
The person has disclosed that they have no political exposure.

relationshipobject
The relationship that this person has with the Account’s business or legal entity.
- relationship.authorizerboolean
  Whether the individual is an authorizer of the Account’s legal entity.
- relationship.directorboolean
  Indicates whether the person is a director of the associated legal entity.
- relationship.executiveboolean
  Indicates whether the person is an executive of the associated legal entity.
- relationship.legal_guardianboolean
  Indicates whether the person is a legal guardian of the associated legal entity.
- relationship.ownerboolean
  Indicates whether the person is an owner of the associated legal entity.
- relationship.percent_ownershipdecimal
  The percentage of ownership the person has in the associated legal entity.
- relationship.representativeboolean
  Indicates whether the person is a representative of the associated legal entity.
- relationship.titlestring
  The title or position the person holds in the associated legal entity.

script_addressesobject
The script addresses (e.g., non-Latin characters) associated with the person.
- script_addresses.kanaobject
  Kana Address.
  script_addresses.kana.citystring
  City, district, suburb, town, or village.
  script_addresses.kana.countryenum
  Two-letter country code (ISO 3166-1 alpha-2).
  script_addresses.kana.line1string
  Address line 1 (e.g., street, PO Box, or company name).
  script_addresses.kana.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
  script_addresses.kana.postal_codestring
  ZIP or postal code.
  script_addresses.kana.statestring
  State, county, province, or region.
  script_addresses.kana.townstring
  Town or cho-me.
- script_addresses.kanjiobject
  Kanji Address.
  script_addresses.kanji.citystring
  City, district, suburb, town, or village.
  script_addresses.kanji.countryenum
  Two-letter country code (ISO 3166-1 alpha-2).
  script_addresses.kanji.line1string
  Address line 1 (e.g., street, PO Box, or company name).
  script_addresses.kanji.line2string
  Address line 2 (e.g., apartment, suite, unit, or building).
  script_addresses.kanji.postal_codestring
  ZIP or postal code.
  script_addresses.kanji.statestring
  State, county, province, or region.
  script_addresses.kanji.townstring
  Town or cho-me.

script_namesobject
The script names (e.g. non-Latin characters) associated with the person.
- script_names.kanaobject
  Persons name in kana script.
  script_names.kana.given_namestring
  The person’s first or given name.
  script_names.kana.surnamestring
  The person’s last or family name.
- script_names.kanjiobject
  Persons name in kanji script.
  script_names.kanji.given_namestring
  The person’s first or given name.
  script_names.kanji.surnamestring
  The person’s last or family name.

surnamestring
The person’s last name.

Returns

Response attributes

idstring
Unique identifier for the token.

objectstring, value is "v2.core.account_person_token"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Time at which the token was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

expires_attimestamp
Time at which the token will expire.

livemodeboolean
Has the value true if the token exists in live mode or the value false if the object exists in test mode.

usedboolean
Determines if the token has already been used (tokens can only be used once).

Error Codes

400token_must_be_created_with_publishable_key

Token must be created with publishable key.

POST /v2/core/accounts/:id/person_tokens

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/person_tokens \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-11-17.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "address": {
        "line1": "27 Fredrick Ave",
        "city": "Brothers",
        "postal_code": "97712",
        "state": "OR",
        "country": "US"
    },
    "id_numbers": [
        {
            "type": "us_ssn_last_4",
            "value": "0000"
        }
    ],
    "relationship": {
        "owner": true,
        "percent_ownership": "0.8",
        "representative": true,
        "title": "CEO"
    }
  }'

Response

{
  "id": "perstok_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY",
  "object": "v2.core.account_person_token",
  "created": "2025-11-17T14:00:00.000Z",
  "expires_at": "2025-11-17T14:10:00.000Z",
  "livemode": true,
  "used": false
}

Need help? Contact Support.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc

Create a Person Token v2

Parameters

account_idstringRequired

additional_addressesarray of objects

additional_addresses.citystring

additional_addresses.countryenum

additional_addresses.line1string

additional_addresses.line2string

additional_addresses.postal_codestring

additional_addresses.purposeenumRequired

additional_addresses.statestring

additional_addresses.townstring

additional_namesarray of objects

additional_names.full_namestring

additional_names.given_namestring

additional_names.purposeenumRequired

additional_names.surnamestring

additional_terms_of_serviceobject

additional_terms_of_service.accountobject

additional_terms_of_service.account.shown_and_acceptedboolean

addressobject

address.citystring

address.countryenum

address.line1string

address.line2string

address.postal_codestring

address.statestring

address.townstring

date_of_birthobject

date_of_birth.dayintegerRequired

date_of_birth.monthintegerRequired

date_of_birth.yearintegerRequired

documentsobject

documents.company_authorizationobject

documents.company_authorization.filesarray of stringsRequired

documents.company_authorization.typeenumRequired

documents.passportobject

documents.passport.filesarray of stringsRequired

documents.passport.typeenumRequired

documents.primary_verificationobject

documents.primary_verification.front_backobjectRequired

documents.primary_verification.front_back.backstring

documents.primary_verification.front_back.frontstring

documents.primary_verification.typeenumRequired

documents.secondary_verificationobject

documents.secondary_verification.front_backobjectRequired

documents.secondary_verification.front_back.backstring

documents.secondary_verification.front_back.frontstring

documents.secondary_verification.typeenumRequired

documents.visaobject

documents.visa.filesarray of stringsRequired

documents.visa.typeenumRequired

emailstring

given_namestring

id_numbersarray of objects

id_numbers.typeenumRequired

id_numbers.valuestringRequired

legal_genderenum

metadatamap

nationalitiesarray of enums

phonestring

political_exposureenum

relationshipobject

relationship.authorizerboolean

relationship.directorboolean

relationship.executiveboolean

relationship.legal_guardianboolean

relationship.ownerboolean

relationship.percent_ownershipdecimal

relationship.representativeboolean

relationship.titlestring

script_addressesobject

script_addresses.kanaobject

script_addresses.kana.citystring

script_addresses.kana.countryenum

script_addresses.kana.line1string

script_addresses.kana.line2string

script_addresses.kana.postal_codestring

script_addresses.kana.statestring

script_addresses.kana.townstring