Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Retrieve a person v2

Retrieves a Person associated with an Account.

Learn more about calling API v2 endpoints.

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 gender person.

    male

    Male gender person.

  • 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
400account_not_yet_compatible_with_v2

Account is not yet compatible with V2 APIs.

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

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.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

GET /v2/core/accounts/:id/persons/:id
curl https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/persons/person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-12-15.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"
    }
  ],
  "livemode": true,
  "metadata": {},
  "nationalities": [],
  "relationship": {
    "owner": true,
    "percent_ownership": "0.8",
    "representative": true,
    "title": "CEO"
  },
  "surname": "Rosen",
  "updated": "2024-11-26T17:12:55.000Z"
}

List persons v2

Returns a paginated list of Persons associated with an Account.

Learn more about calling API v2 endpoints.

Parameters

  • account_idstringRequired

    Account the Persons are associated with.

  • limitinteger

    The upper limit on the number of accounts returned by the List Account request.

  • pagestring

    The page token to navigate to next or previous batch of accounts given by the list request.

Returns

Response attributes

  • dataarray of objects

    A list of retrieved Person objects.

  • next_page_urlnullable string

    URL with page token to navigate to next batch of Persons given by the list request.

  • previous_page_urlnullable string

    URL with page token to previous to next batch of Persons given by the list request.

Error Codes
400account_not_yet_compatible_with_v2

Account is not yet compatible with V2 APIs.

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

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.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

GET /v2/core/accounts/:id/persons
curl https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/persons \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-12-15.preview"
Response
{
  "data": [
    {
      "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"
        }
      ],
      "livemode": true,
      "metadata": {},
      "nationalities": [],
      "relationship": {
        "owner": true,
        "percent_ownership": "0.8",
        "representative": true,
        "title": "CEO"
      },
      "surname": "Rosen",
      "updated": "2024-11-26T17:12:55.000Z"
    }
  ]
}

Delete a person v2

Delete a Person associated with an Account.

Learn more about calling API v2 endpoints.

Parameters

  • account_idstringRequired

    The Account the Person is associated with.

  • idstringRequired

    The ID of the Person to delete.

Returns

Response attributes

  • idstring

    Person deleted.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • deletedboolean

    Always true for a deleted object.

Error Codes
400account_not_yet_compatible_with_v2

Account is not yet compatible with V2 APIs.

400accounts_v2_access_blocked

Accounts v2 is not enabled for your platform.

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.

429account_rate_limit_exceeded

Account cannot exceed a configured concurrency rate limit on updates.

DELETE /v2/core/accounts/:id/persons/:id
curl -X DELETE https://api.stripe.com/v2/core/accounts/acct_1Nv0FGQ9RKHgCVdK/persons/person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-12-15.preview"
Response
{
  "id": "person_test_61RS0CgWt1xBt8M1Q16RS0Cg0WSQO5ZXUVpZxZ9tAIbY",
  "object": "v2.core.account_person",
  "deleted": true
}

Person event types v2

This is a list of all public thin events we currently send for updates to Person, which are continually evolving and expanding. The payload of thin events is unversioned. During processing, you must fetch the versioned event from the API or fetch the resource’s current state.

Event types

Type
Filter events by type