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

Server-side language

curl https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -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_exposurestring

registered_addressobject

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_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

Server-side language

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

List all persons

Returns a list of people associated with the account’s legal entity. The people are returned sorted by creation date, with the most recent people appearing first.

Parameters

relationshipobject
Filters on the list of people returned based on the person’s relationship to the account’s company.

More parameters

ending_beforestring

limitinteger

starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit people, starting after person starting_after. Each entry in the array is a separate person object. If no more people are available, the resulting array will be empty.

GET /v1/accounts/:id/persons

Server-side language

curl -G https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
  -d limit=3

Response

{
  "object": "list",
  "url": "/v1/accounts/acct_1032D82eZvKYlo2C/persons",
  "has_more": false,
  "data": [
    {
      "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": {},
      "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"
      }
    }
  ]
}

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

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_exposurestring

registered_addressobject

verificationobject

Returns

Update 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

More attributes

More parameters

More parameters

More parameters