Person

This is an object representing a person associated with a Stripe account.

A platform cannot access a Standard or Express account’s persons after the account starts onboarding, such as after generating an account link for the account. See the Standard onboarding or Express onboarding documentation for information about platform prefilling and account onboarding steps.

Related guide: Handling identity verification with the API

The Person object

Attributes

  • idstring

    Unique identifier for the object.

  • accountstring

    The account the person is associated with.

  • addressnullable object

    The person’s address.

  • dobnullable object

    The person’s date of birth.

  • emailnullable string

    The person’s email address.

  • first_namenullable string

    The person’s first name.

  • last_namenullable string

    The person’s last name.

  • metadataobject

    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.

  • phonenullable string

    The person’s phone number.

  • relationshipobject

    Describes the person’s relationship to the account.

  • requirementsnullable object

    Information about the requirements for this person, including what information needs to be collected, and by when.

More attributes

  • objectstring

  • additional_tos_acceptancesobject

  • address_kananullable object

  • address_kanjinullable object

  • createdtimestamp

  • first_name_kananullable string

  • first_name_kanjinullable string

  • full_name_aliasesnullable array of strings

  • future_requirementsnullable object

  • gendernullable enum

  • id_number_providedboolean

  • id_number_secondary_providednullable boolean

  • last_name_kananullable string

  • last_name_kanjinullable string

  • maiden_namenullable string

  • nationalitynullable string

  • political_exposurenullable enum

  • registered_addressnullable object

  • ssn_last_4_providedboolean

  • verificationobject

Create a person

Creates a new person.

Parameters

  • addressobject

    The person’s address.

  • dobobject

    The person’s date of birth.

  • emailstring

    The person’s email address.

  • first_namestring

    The person’s first name.

  • id_numberstring

    The person’s ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. Instead of the number itself, you can also provide a PII token provided by Stripe.js.

  • last_namestring

    The person’s last name.

  • metadataobject

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phonestring

    The person’s phone number.

  • relationshipobject

    The relationship that this person has with the account’s legal entity.

  • ssn_last_4string

    The last four digits of the person’s Social Security number (U.S. only).

More parameters

  • additional_tos_acceptancesobject

  • address_kanaobject

  • address_kanjiobject

  • documentsobject

  • first_name_kanastring

  • first_name_kanjistring

  • full_name_aliasesarray of strings

  • genderenum

  • id_number_secondarystring

  • last_name_kanastring

  • last_name_kanjistring

  • maiden_namestring

  • nationalitystring

  • person_tokenstring

  • political_exposurestring

  • registered_addressobject

  • verificationobject

Returns

Returns a person object.

POST /v1/accounts/:id/persons
curl -X POST https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
"id": "person_1N9XNb2eZvKYlo2CjPX7xF6F",
"object": "person",
"account": "acct_1032D82eZvKYlo2C",
"created": 1684518375,
"dob": {
"day": null,
"month": null,
"year": null
},
"first_name": null,
"future_requirements": {
"alternatives": [],
"currently_due": [],
"errors": [],
"eventually_due": [],
"past_due": [],
"pending_verification": []
},
"id_number_provided": false,
"last_name": null,
"metadata": {},
"relationship": {
"director": false,
"executive": false,
"owner": false,
"percent_ownership": null,
"representative": false,
"title": null
},
"requirements": {
"alternatives": [],
"currently_due": [],
"errors": [],
"eventually_due": [],
"past_due": [],
"pending_verification": []
},
"ssn_last_4_provided": false,
"verification": {
"additional_document": {
"back": null,
"details": null,
"details_code": null,
"front": null
},
"details": null,
"details_code": null,
"document": {
"back": null,
"details": null,
"details_code": null,
"front": null
},
"status": "unverified"
}
}

Update a person

Updates an existing person.

Parameters

  • addressobject

    The person’s address.

  • dobobject

    The person’s date of birth.

  • emailstring

    The person’s email address.

  • first_namestring

    The person’s first name.

  • id_numberstring

    The person’s ID number, as appropriate for their country. For example, a social security number in the U.S., social insurance number in Canada, etc. Instead of the number itself, you can also provide a PII token provided by Stripe.js.

  • last_namestring

    The person’s last name.

  • metadataobject

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • phonestring

    The person’s phone number.

  • relationshipobject

    The relationship that this person has with the account’s legal entity.

  • ssn_last_4string

    The last four digits of the person’s Social Security number (U.S. only).

More parameters

  • additional_tos_acceptancesobject

  • address_kanaobject

  • address_kanjiobject

  • documentsobject

  • first_name_kanastring

  • first_name_kanjistring

  • full_name_aliasesarray of strings

  • genderenum

  • id_number_secondarystring

  • last_name_kanastring

  • last_name_kanjistring

  • maiden_namestring

  • nationalitystring

  • person_tokenstring

  • political_exposurestring

  • registered_addressobject

  • verificationobject

Returns

Returns a person object.

POST /v1/accounts/:id/persons/:id
curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons/person_1MqjB62eZvKYlo2CaeEJzKVR \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d "metadata[order_id]"=6735
Response
{
"id": "person_1MqjB62eZvKYlo2CaeEJzKVR",
"person": "person_1MqjB62eZvKYlo2CaeEJzKVR",
"object": "person",
"account": "acct_1032D82eZvKYlo2C",
"created": 1680035496,
"dob": {
"day": null,
"month": null,
"year": null
},
"first_name": "Jane",
"future_requirements": {
"alternatives": [],
"currently_due": [],
"errors": [],
"eventually_due": [],
"past_due": [],
"pending_verification": []
},
"id_number_provided": false,
"last_name": "Diaz",
"metadata": {
"order_id": "6735"
},
"relationship": {
"director": false,
"executive": false,
"owner": false,
"percent_ownership": null,
"representative": false,
"title": null
},
"requirements": {
"alternatives": [],
"currently_due": [],
"errors": [],
"eventually_due": [],
"past_due": [],
"pending_verification": []
},
"ssn_last_4_provided": false,
"verification": {
"additional_document": {
"back": null,
"details": null,
"details_code": null,
"front": null
},
"details": null,
"details_code": null,
"document": {
"back": null,
"details": null,
"details_code": null,
"front": null
},
"status": "unverified"
}
}

Retrieve a person

Retrieves an existing person.

Parameters

No parameters.

Returns

Returns a person object.

GET /v1/accounts/:id/persons/:id
curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons/person_1MqjB62eZvKYlo2CaeEJzKVR \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
Response
{
"id": "person_1N9XNb2eZvKYlo2CjPX7xF6F",
"object": "person",
"account": "acct_1032D82eZvKYlo2C",
"created": 1684518375,
"dob": {
"day": null,
"month": null,
"year": null
},
"first_name": null,
"future_requirements": {
"alternatives": [],
"currently_due": [],
"errors": [],
"eventually_due": [],
"past_due": [],
"pending_verification": []
},
"id_number_provided": false,
"last_name": null,
"metadata": {},
"relationship": {
"director": false,
"executive": false,
"owner": false,
"percent_ownership": null,
"representative": false,
"title": null
},
"requirements": {
"alternatives": [],
"currently_due": [],
"errors": [],
"eventually_due": [],
"past_due": [],
"pending_verification": []
},
"ssn_last_4_provided": false,
"verification": {
"additional_document": {
"back": null,
"details": null,
"details_code": null,
"front": null
},
"details": null,
"details_code": null,
"document": {
"back": null,
"details": null,
"details_code": null,
"front": null
},
"status": "unverified"
}
}
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$