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

Delete a person

Deletes an existing person’s relationship to the account’s legal entity. Any person with a relationship for an account can be deleted through the API, except if the person is the account_opener. If your integration is using the executive parameter, you cannot delete the only verified executive on file.

Parameters

No parameters.

Returns

Returns the deleted person object.

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

Server-side language

curl -X DELETE https://api.stripe.com/v1/accounts/acct_1032D82eZvKYlo2C/persons/person_1MqjB62eZvKYlo2CaeEJzKVR \
  -u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"

Response

{
  "id": "person_1MqjB62eZvKYlo2CaeEJzKVR",
  "object": "person",
  "deleted": true
}

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

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

Retrieve a person

Parameters

Returns

List all persons

Parameters

relationshipobject

More parametersExpand all

ending_beforestring

limitinteger

starting_afterstring

Returns

Delete a person

Parameters

Returns

More parameters

More parameters

More parameters