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 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_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

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/: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: 2026-01-28.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
}

Retrieve a Person Token v2

Retrieves a Person Token associated with an Account.

Learn more about calling API v2 endpoints.

Parameters

account_idstringRequired
The Account the Person is associated with.

idstringRequired
The ID of the Person Token to retrieve.

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

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/:id/person_tokens/:id

curl https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/person_tokens/perstok_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-01-28.preview"

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
}

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

account_idstringRequired

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

account_idstringRequired

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.core.account_person_token"

createdtimestamp

expires_attimestamp

livemodeboolean

usedboolean