Persons v2

Learn more about calling API v2 endpoints.

Person retrieval response schema.

Endpoints

POST/v2/core/accounts/:id/persons

POST/v2/core/accounts/:id/persons/:id

GET/v2/core/accounts/:id/persons/:id

GET/v2/core/accounts/:id/persons

DELETE/v2/core/accounts/:id/persons/:id

The Person object

Attributes

idstring
Unique identifier for the Person.

objectstring, value is "v2.core.account_person"
String representing the object’s type. Objects of the same type share the same value of the object field.

accountstring
The account ID which the individual belongs to.

additional_addressesnullable array of objects
Additional addresses associated with the person.

additional_namesnullable array of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_servicenullable object
Attestations of accepted terms of service agreements.

addressnullable object
The person’s residential address.

createdtimestamp
Time at which the object was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

date_of_birthnullable object
The person’s date of birth.

documentsnullable object
Documents that may be submitted to satisfy various informational requests.

emailnullable string
The person’s email address.

given_namenullable string
The person’s first name.

id_numbersnullable array of objects
The identification numbers (e.g., SSN) associated with the person.

legal_gendernullable enum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

nationalitiesnullable array of enums
The countries where the person is a national. Two-letter country code (ISO 3166-1 alpha-2).

phonenullable string
The person’s phone number.

political_exposurenullable 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.

relationshipnullable object
The relationship that this person has with the Account’s business or legal entity.

script_addressesnullable object
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesnullable object
The script names (e.g. non-Latin characters) associated with the person.

surnamenullable string
The person’s last name.

updatedtimestamp
Time at which the object was last updated. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

The Person object

{
  "id": "person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY",
  "object": "v2.core.account_person",
  "account": "acct_1Nv0FGQ9RKHgCVdK",
  "additional_addresses": [],
  "additional_names": [],
  "address": {
    "city": "Brothers",
    "country": "us",
    "line1": "27 Fredrick Ave",
    "postal_code": "97712",
    "state": "OR"
  },
  "created": "2024-11-26T17:10:07.000Z",
  "email": "jenny.rosen@example.com",
  "given_name": "Jenny",
  "id_numbers": [
    {
      "type": "us_ssn_last_4"
    }
  ],
  "metadata": {},
  "nationalities": [],
  "relationship": {
    "owner": true,
    "percent_ownership": "0.8",
    "representative": true,
    "title": "CEO"
  },
  "surname": "Rosen",
  "updated": "2024-11-26T17:10:07.000Z"
}

Create a Person v2

Learn more about calling API v2 endpoints.

Create a Person associated with an Account.

Parameters

account_idstringRequired
Account the Person should be associated with.

additional_addressesarray of objects
Additional addresses associated with the person.

additional_namesarray of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_serviceobject
Attestations of accepted terms of service agreements.

addressobject
The person’s residential address.

date_of_birthobject
The person’s date of birth.

documentsobject
Documents that may be submitted to satisfy various informational requests.

emailstring
Email.

given_namestring
The person’s first name.

id_numbersarray of objects
The identification numbers (e.g., SSN) associated with the person.

legal_genderenum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

metadatamap
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.

nationalitiesarray of enums
The nationalities (countries) this person is associated with.

phonestring
The phone number for this person.

political_exposureenum
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.

relationshipobject
The relationship that this person has with the Account’s business or legal entity.

script_addressesobject
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesobject
The script names (e.g. non-Latin characters) associated with the person.

surnamestring
The person’s last name.

Returns

Response attributes

idstring
Unique identifier for the Person.

objectstring, value is "v2.core.account_person"
String representing the object’s type. Objects of the same type share the same value of the object field.

accountstring
The account ID which the individual belongs to.

additional_addressesnullable array of objects
Additional addresses associated with the person.

additional_namesnullable array of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_servicenullable object
Attestations of accepted terms of service agreements.

addressnullable object
The person’s residential address.

createdtimestamp
Time at which the object was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

date_of_birthnullable object
The person’s date of birth.

documentsnullable object
Documents that may be submitted to satisfy various informational requests.

emailnullable string
The person’s email address.

given_namenullable string
The person’s first name.

id_numbersnullable array of objects
The identification numbers (e.g., SSN) associated with the person.

legal_gendernullable enum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

nationalitiesnullable array of enums
The countries where the person is a national. Two-letter country code (ISO 3166-1 alpha-2).

phonenullable string
The person’s phone number.

political_exposurenullable 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.

relationshipnullable object
The relationship that this person has with the Account’s business or legal entity.

script_addressesnullable object
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesnullable object
The script names (e.g. non-Latin characters) associated with the person.

surnamenullable string
The person’s last name.

updatedtimestamp
Time at which the object was last updated. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

Error Codes

400additional_legal_guardian_not_allowed

More than one legal guardian is added to an account.

400additional_representative_not_allowed

More than one representative is added to an account.

400additional_tos_only_allowed_for_legal_guardian

Additional terms of service are signed by someone other than the legal guardian.

400address_characters_invalid

Invalid characters are provided for address fields.

400address_country_identity_country_mismatch

Address country doesn’t match identity country.

400address_country_mismatch

Registered/script address country doesn’t match residential address country.

400address_country_required

Address country is required but not provided.

400address_postal_code_invalid

Address postal code is invalid.

400address_state_invalid

Address state is invalid.

400address_town_invalid

Address town is invalid.

400date_of_birth_age_restriction

Representative date of birth does not meet the age limit.

400date_of_birth_invalid

Representative date of birth is provided an invalid date or a future date.

400document_invalid

Provided file tokens for documents are invalid, not found, deleted, or belong to a different account.

400document_purpose_invalid

Provided file tokens for documents are of the wrong purpose.

400duplicate_person_not_allowed

Duplicate person is added to an account.

400email_domain_invalid_for_recipient

Email contains unsupported domain.

400email_invalid

Incorrect email is provided.

400id_number_invalid

Provided ID number is of the wrong format for the given type.

400identity_country_required

The identity.country value is required but not provided.

400incorrect_id_number_for_country

Incorrect ID number is provided for a country.

400individual_additional_person_not_allowed

Additional person is added for an individual business type.

400ip_address_invalid

Invalid IP address is provided.

400legal_guardian_representative_not_allowed

Person is designated as both legal guardian and representative.

400legal_guardian_requires_existing_representative

A legal guardian may not be added to the account without an existing representative.

400non_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

400person_percent_ownership_invalid

Error returned when relationship.owner is set to true but the ownership percentage is set to 0%.

400phone_invalid

Phone number is invalid.

400script_characters_invalid

Provided script characters are invalid for the script.

400total_person_ownership_exceeded

Total ownership percentages of all Persons on the account exceeds 100%.

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

POST /v2/core/accounts/:id/persons

Server-side language

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/persons \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "given_name": "Jenny",
    "surname": "Rosen",
    "email": "jenny.rosen@example.com",
    "address": {
        "line1": "27 Fredrick Ave",
        "city": "Brothers",
        "postal_code": "97712",
        "state": "OR",
        "country": "us"
    },
    "id_numbers": [
        {
            "type": "us_ssn_last_4",
            "value": "0000"
        }
    ],
    "relationship": {
        "owner": true,
        "percent_ownership": "0.8",
        "representative": true,
        "title": "CEO"
    }
  }'

Response

{
  "id": "person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY",
  "object": "v2.core.account_person",
  "account": "acct_1Nv0FGQ9RKHgCVdK",
  "additional_addresses": [],
  "additional_names": [],
  "address": {
    "city": "Brothers",
    "country": "us",
    "line1": "27 Fredrick Ave",
    "postal_code": "97712",
    "state": "OR"
  },
  "created": "2024-11-26T17:10:07.000Z",
  "email": "jenny.rosen@example.com",
  "given_name": "Jenny",
  "id_numbers": [
    {
      "type": "us_ssn_last_4"
    }
  ],
  "metadata": {},
  "nationalities": [],
  "relationship": {
    "owner": true,
    "percent_ownership": "0.8",
    "representative": true,
    "title": "CEO"
  },
  "surname": "Rosen",
  "updated": "2024-11-26T17:10:07.000Z"
}

Update a Person v2

Learn more about calling API v2 endpoints.

Updates a Person associated with an Account.

Parameters

account_idstringRequired
The Account the Person is associated with.

idstringRequired
The ID of the Person to update.

additional_addressesarray of objects
Additional addresses associated with the person.

additional_namesarray of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_serviceobject
Attestations of accepted terms of service agreements.

addressobject
The primary address associated with the person.

date_of_birthobject
The person’s date of birth.

documentsobject
Documents that may be submitted to satisfy various informational requests.

emailstring
Email.

given_namestring
The person’s first name.

id_numbersarray of objects
The identification numbers (e.g., SSN) associated with the person.

legal_genderenum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

metadatamap
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.

nationalitiesarray of enums
The nationalities (countries) this person is associated with.

phonestring
The phone number for this person.

political_exposureenum
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.

relationshipobject
The relationship that this person has with the Account’s business or legal entity.

script_addressesobject
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesobject
The script names (e.g. non-Latin characters) associated with the person.

surnamestring
The person’s last name.

Returns

Response attributes

idstring
Unique identifier for the Person.

objectstring, value is "v2.core.account_person"
String representing the object’s type. Objects of the same type share the same value of the object field.

accountstring
The account ID which the individual belongs to.

additional_addressesnullable array of objects
Additional addresses associated with the person.

additional_namesnullable array of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_servicenullable object
Attestations of accepted terms of service agreements.

addressnullable object
The person’s residential address.

createdtimestamp
Time at which the object was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

date_of_birthnullable object
The person’s date of birth.

documentsnullable object
Documents that may be submitted to satisfy various informational requests.

emailnullable string
The person’s email address.

given_namenullable string
The person’s first name.

id_numbersnullable array of objects
The identification numbers (e.g., SSN) associated with the person.

legal_gendernullable enum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

nationalitiesnullable array of enums
The countries where the person is a national. Two-letter country code (ISO 3166-1 alpha-2).

phonenullable string
The person’s phone number.

political_exposurenullable 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.

relationshipnullable object
The relationship that this person has with the Account’s business or legal entity.

script_addressesnullable object
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesnullable object
The script names (e.g. non-Latin characters) associated with the person.

surnamenullable string
The person’s last name.

updatedtimestamp
Time at which the object was last updated. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

Error Codes

400additional_legal_guardian_not_allowed

More than one legal guardian is added to an account.

400additional_representative_not_allowed

More than one representative is added to an account.

400additional_tos_only_allowed_for_legal_guardian

Additional terms of service are signed by someone other than the legal guardian.

400address_characters_invalid

Invalid characters are provided for address fields.

400address_country_identity_country_mismatch

Address country doesn’t match identity country.

400address_country_mismatch

Registered/script address country doesn’t match residential address country.

400address_country_required

Address country is required but not provided.

400address_postal_code_invalid

Address postal code is invalid.

400address_state_invalid

Address state is invalid.

400address_town_invalid

Address town is invalid.

400date_of_birth_age_restriction

Representative date of birth does not meet the age limit.

400date_of_birth_invalid

Representative date of birth is provided an invalid date or a future date.

400document_invalid

Provided file tokens for documents are invalid, not found, deleted, or belong to a different account.

400document_purpose_invalid

Provided file tokens for documents are of the wrong purpose.

400duplicate_person_not_allowed

Duplicate person is added to an account.

400email_domain_invalid_for_recipient

Email contains unsupported domain.

400email_invalid

Incorrect email is provided.

400id_number_invalid

Provided ID number is of the wrong format for the given type.

400identity_country_required

The identity.country value is required but not provided.

400immutable_identity_param

Identity param has been made immutable due to the state of the account.

400incorrect_id_number_for_country

Incorrect ID number is provided for a country.

400ip_address_invalid

Invalid IP address is provided.

400legal_guardian_representative_not_allowed

Person is designated as both legal guardian and representative.

400legal_guardian_requires_existing_representative

A legal guardian may not be added to the account without an existing representative.

400non_jp_kana_kanji_address

Kana Kanji script addresses must have JP country.

400person_percent_ownership_invalid

Error returned when relationship.owner is set to true but the ownership percentage is set to 0%.

400phone_invalid

Phone number is invalid.

400script_characters_invalid

Provided script characters are invalid for the script.

400total_person_ownership_exceeded

Total ownership percentages of all Persons on the account exceeds 100%.

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

404not_found

The resource wasn’t found.

POST /v2/core/accounts/:id/persons/:id

Server-side language

curl -X POST https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/persons/person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-03-31.preview" \
  --json '{
    "date_of_birth": {
        "day": 28,
        "month": 1,
        "year": 2000
    }
  }'

Response

{
  "id": "person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY",
  "object": "v2.core.account_person",
  "account": "acct_1Nv0FGQ9RKHgCVdK",
  "additional_addresses": [],
  "additional_names": [],
  "address": {
    "city": "Brothers",
    "country": "us",
    "line1": "27 Fredrick Ave",
    "postal_code": "97712",
    "state": "OR"
  },
  "created": "2024-11-26T17:10:07.000Z",
  "date_of_birth": {
    "day": 28,
    "month": 1,
    "year": 2000
  },
  "email": "jenny.rosen@example.com",
  "given_name": "Jenny",
  "id_numbers": [
    {
      "type": "us_ssn_last_4"
    }
  ],
  "metadata": {},
  "nationalities": [],
  "relationship": {
    "owner": true,
    "percent_ownership": "0.8",
    "representative": true,
    "title": "CEO"
  },
  "surname": "Rosen",
  "updated": "2024-11-26T17:12:55.000Z"
}

Retrieve a Person v2

Learn more about calling API v2 endpoints.

Retrieves a Person associated with an Account.

Parameters

account_idstringRequired
The Account the Person is associated with.

idstringRequired
The ID of the Person to retrieve.

Returns

Response attributes

idstring
Unique identifier for the Person.

objectstring, value is "v2.core.account_person"
String representing the object’s type. Objects of the same type share the same value of the object field.

accountstring
The account ID which the individual belongs to.

additional_addressesnullable array of objects
Additional addresses associated with the person.

additional_namesnullable array of objects
Additional names (e.g. aliases) associated with the person.

additional_terms_of_servicenullable object
Attestations of accepted terms of service agreements.

addressnullable object
The person’s residential address.

createdtimestamp
Time at which the object was created. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

date_of_birthnullable object
The person’s date of birth.

documentsnullable object
Documents that may be submitted to satisfy various informational requests.

emailnullable string
The person’s email address.

given_namenullable string
The person’s first name.

id_numbersnullable array of objects
The identification numbers (e.g., SSN) associated with the person.

legal_gendernullable enum
The person’s gender (International regulations require either “male” or “female”).
Possible enum values
female
Female person gender.
male
Male person gender.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

nationalitiesnullable array of enums
The countries where the person is a national. Two-letter country code (ISO 3166-1 alpha-2).

phonenullable string
The person’s phone number.

political_exposurenullable 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.

relationshipnullable object
The relationship that this person has with the Account’s business or legal entity.

script_addressesnullable object
The script addresses (e.g., non-Latin characters) associated with the person.

script_namesnullable object
The script names (e.g. non-Latin characters) associated with the person.

surnamenullable string
The person’s last name.

updatedtimestamp
Time at which the object was last updated. Represented as a RFC 3339 date & time UTC value in millisecond precision, for example: 2022-09-18T13:22:18.123Z.

Error Codes

400v1_account_instead_of_v2_account

V1 Account ID cannot be used in V2 Account APIs.

400v1_customer_instead_of_v2_account

V1 Customer ID cannot be used in V2 Account APIs.

404not_found

The resource wasn’t found.

GET /v2/core/accounts/:id/persons/:id

Server-side language

curl https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/persons/person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY \
  -H "Authorization: Bearer {{YOUR_API_KEY}}{{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2025-03-31.preview"

Response

{
  "id": "person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY",
  "object": "v2.core.account_person",
  "account": "acct_1Nv0FGQ9RKHgCVdK",
  "additional_addresses": [],
  "additional_names": [],
  "address": {
    "city": "Brothers",
    "country": "us",
    "line1": "27 Fredrick Ave",
    "postal_code": "97712",
    "state": "OR"
  },
  "created": "2024-11-26T17:10:07.000Z",
  "date_of_birth": {
    "day": 28,
    "month": 1,
    "year": 2000
  },
  "email": "jenny.rosen@example.com",
  "given_name": "Jenny",
  "id_numbers": [
    {
      "type": "us_ssn_last_4"
    }
  ],
  "metadata": {},
  "nationalities": [],
  "relationship": {
    "owner": true,
    "percent_ownership": "0.8",
    "representative": true,
    "title": "CEO"
  },
  "surname": "Rosen",
  "updated": "2024-11-26T17:12:55.000Z"
}

Persons v2

The Person object

Attributes

idstring

objectstring, value is "v2.core.account_person"

accountstring

additional_addressesnullable array of objects

additional_namesnullable array of objects

additional_terms_of_servicenullable object

addressnullable object

createdtimestamp

date_of_birthnullable object

documentsnullable object

emailnullable string

given_namenullable string

id_numbersnullable array of objects

legal_gendernullable enum

livemodeboolean

metadatanullable map

nationalitiesnullable array of enums

phonenullable string

political_exposurenullable enum

relationshipnullable object

script_addressesnullable object

script_namesnullable object

surnamenullable string

updatedtimestamp

Create a Person v2

Parameters

account_idstringRequired

additional_addressesarray of objects

additional_namesarray of objects

additional_terms_of_serviceobject

addressobject

date_of_birthobject

documentsobject

emailstring

given_namestring

id_numbersarray of objects

legal_genderenum

metadatamap

nationalitiesarray of enums

phonestring

political_exposureenum

relationshipobject

script_addressesobject

script_namesobject

surnamestring

Returns

Response attributes

idstring

objectstring, value is "v2.core.account_person"

accountstring

additional_addressesnullable array of objects

additional_namesnullable array of objects

additional_terms_of_servicenullable object

addressnullable object

createdtimestamp

date_of_birthnullable object

documentsnullable object

emailnullable string

given_namenullable string

id_numbersnullable array of objects

legal_gendernullable enum

livemodeboolean

metadatanullable map

nationalitiesnullable array of enums

phonenullable string

political_exposurenullable enum

relationshipnullable object

script_addressesnullable object

script_namesnullable object

surnamenullable string

updatedtimestamp

Update a Person v2

Parameters

account_idstringRequired

idstringRequired

additional_addressesarray of objects

additional_namesarray of objects