Person Tokens v2

Person Tokens are single-use tokens which tokenize person information, and are used for creating or updating a Person.

Learn more about calling API v2 endpoints.

Was this section helpful?Yes No

Create a person token

POST/v2/core/accounts/:account_id/person_tokens

Retrieve a person token

GET/v2/core/accounts/:account_id/person_tokens/:id

The Person Token object v2

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).

The Person Token object

{
  "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
}

Create a person token v2

Creates a single-use token that represents the details for a person. Use this when you create or update persons associated with an Account v2. Learn more about account tokens. You can only create person tokens with your application’s publishable key and in live mode. You can use your application’s secret key to create person tokens only in test mode.

Learn more about calling API v2 endpoints.

Parameters

additional_addressesarray of objects
Additional addresses associated with the person.

additional_namesarray of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_serviceobject
Attestations of accepted terms of service agreements.

addressobject
The person’s residential address.

date_of_birthobject
The person’s date of birth.

documentsobject
Documents that may be submitted to satisfy various informational requests.

emailstring
Email.

given_namestring
The person’s first name.

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

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

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.

script_addressesobject
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesobject
The script names (e.g. non-Latin characters) associated with the person.

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

400non_connect_platform_accounts_v2_access_blocked

Needs to use the newer API version or onboard to Connect.

400platform_registration_required

The direct merchant has not signed up for Connect and cannot create connected accounts.

400token_must_be_created_with_publishable_key

Token must be created with publishable key.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

POST /v2/core/accounts/:account_id/person_tokens

curl -X POST https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/person_tokens \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-04-22.dahlia" \
  --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
}

Retrieve a person token v2

Retrieves a Person Token associated with an Account.

Learn more about calling API v2 endpoints.

Parameters

No parameters.

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

400non_connect_platform_accounts_v2_access_blocked

Needs to use the newer API version or onboard to Connect.

404not_found

The resource wasn’t found.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

GET /v2/core/accounts/:account_id/person_tokens/:id

curl https://api.stripe.com/v2/core/accounts/{{ACCOUNT_ID}}/person_tokens/perstok_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-04-22.dahlia"

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": true
}

Person Tokens v2

The Person Token object v2

Attributes

idstring

objectstring, value is "v2.core.account_person_token"

createdtimestamp

expires_attimestamp

livemodeboolean

usedboolean

Create a person token v2

Parameters

additional_addressesarray of objects

additional_namesarray of objects

additional_terms_of_serviceobject

addressobject

date_of_birthobject

documentsobject

emailstring

given_namestring

id_numbersarray of objects

legal_genderenum

metadatamap

nationalitiesarray of enums

phonestring

political_exposureenum

relationshipobject

script_addressesobject

script_namesobject

surnamestring

Returns

Response attributes

idstring

objectstring, value is "v2.core.account_person_token"

createdtimestamp

expires_attimestamp

livemodeboolean

usedboolean

Retrieve a person token v2

Parameters

Returns

Response attributes

idstring

objectstring, value is "v2.core.account_person_token"

createdtimestamp

expires_attimestamp

livemodeboolean

usedboolean