Person

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

A platform can only access a subset of data in a person for an account where account.controller.requirement_collection is stripe, which includes Standard and Express accounts, after creating an Account Link or Account Session to start Connect onboarding.

See the Standard onboarding or Express onboarding documentation for information about prefilling information and account onboarding steps. Learn more about handling identity verification with the API.

Endpoints

POST/v1/accounts/:id/persons

POST/v1/accounts/:id/persons/:id

GET/v1/accounts/:id/persons/:id

GET/v1/accounts/:id/persons

DELETE/v1/accounts/:id/persons/:id

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. Also available for accounts where controller.requirement_collection is stripe.

first_namenullable string
The person’s first name. Also available for accounts where controller.requirement_collection is stripe.

last_namenullable string
The person’s last name. Also available for accounts where controller.requirement_collection is stripe.

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. Also available for accounts where controller.requirement_collection is stripe.

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

us_cfpb_datanullable object

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_exposureenum

registered_addressobject

us_cfpb_dataobject

verificationobject

Returns

Returns a person object.

POST /v1/accounts/:id/persons

Server-side language

curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d first_name=John \
  -d last_name=Doe

Response

{
  "id": "person_1N9XNb2eZvKYlo2CjPX7xF6F",
  "object": "person",
  "account": "acct_1032D82eZvKYlo2C",
  "created": 1684518375,
  "dob": {
    "day": null,
    "month": null,
    "year": null
  },
  "first_name": "John",
  "future_requirements": {
    "alternatives": [],
    "currently_due": [],
    "errors": [],
    "eventually_due": [],
    "past_due": [],
    "pending_verification": []
  },
  "id_number_provided": false,
  "last_name": "Doe",
  "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_exposureenum

registered_addressobject

us_cfpb_dataobject

verificationobject

Returns

Returns a person object.

POST /v1/accounts/:id/persons/:id

Server-side language

curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons/person_1MqjB62eZvKYlo2CaeEJzKVR \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -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

Server-side language

curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons/person_1MqjB62eZvKYlo2CaeEJzKVR \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"

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"
  }
}

Person

The Person object

Attributes

idstring

accountstring

addressnullable object

dobnullable object

emailnullable string

first_namenullable string

last_namenullable string

metadataobject

phonenullable string

relationshipobject

requirementsnullable object

More attributesExpand all

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

us_cfpb_datanullable object

verificationobject

Create a person

Parameters

addressobject

dobobject

emailstring

first_namestring

id_numberstring

last_namestring

metadataobject

phonestring

relationshipobject

ssn_last_4string

More parametersExpand all

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_exposureenum

registered_addressobject

us_cfpb_dataobject

verificationobject

Returns

Update a person

Parameters

addressobject

dobobject

emailstring

first_namestring

id_numberstring

last_namestring

metadataobject

phonestring

relationshipobject

ssn_last_4string

More attributes

More parameters

More parameters