Core Resources
Payment Methods
Products
Product Catalog
Commerce
Agentic Commerce
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury for Platforms
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

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?YesNo
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

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

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

Returns a Person Token object.

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.

curl -X POST https://api.stripe.com/v2/core/accounts//person_tokens \
  -H "Authorization: Bearer sk_test_BQokikJOvBiI2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2026-09-30.endive" \
  --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
}