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 _ addresses array of objects Additional addresses associated with the person.
additional _ names array of objects Additional names (e.g. aliases) associated with the person.
additional _ terms _ of _ service object Attestations of accepted terms of service agreements.
address object The person’s residential address.
date _ of _ birth object The person’s date of birth.
documents object Documents that may be submitted to satisfy various informational requests.
email string Email.
given _ name string The person’s first name.
id _ numbers array of objects The identification numbers (e.g., SSN) associated with the person.
legal _ gender enum The person’s gender (International regulations require either “male” or “female”). Possible enum values female Female gender person. male Male gender person.
metadata map 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.
nationalities array of enums The nationalities (countries) this person is associated with.
phone string The phone number for this person.
political _ exposure enum 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.
relationship object The relationship that this person has with the Account’s business or legal entity.
script _ addresses object The script addresses (e.g., non-Latin characters) associated with the person.
script _ names object The script names (e.g. non-Latin characters) associated with the person.
surname string The person’s last name.

Returns

Returns a Person Token object.

Error Codes

400 non _ connect _ platform _ accounts _ v2 _ access _ blocked

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

400 platform _ registration _ required

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

400 token _ must _ be _ created _ with _ publishable _ key

Token must be created with publishable key.

429 account _ rate _ limit _ exceeded

Account cannot exceed a configured concurrency rate limit on updates.

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

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

Retrieves a Person Token associated with an Account.