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

id string Unique identifier for the token.
object string, 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.
created timestamp 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 _ at timestamp Time at which the token will expire.
livemode boolean Has the value true if the token exists in live mode or the value false if the object exists in test mode.
used boolean 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 _ 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}