POST/v1/accounts/{account}/persons

Create a person

Creates a new person associated with an account's legal entity. Supply the person's identifying, address, relationship, date-of-birth, and verification information as needed, and use expand to expand response fields. Nested address, date-of-birth, document, and acceptance data must use the structures defined for those fields.

RetriesRetries up to 2×, 500ms backoff, 30s timeout.
IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 29 body fields

accountstringrequired

The account to associate with the new person. Maximum 5000 characters.

Optional form data describing a person and supporting legal-entity verification.

additional_tos_acceptancesobjectoptional

Details on the legal guardian's or authorizer's acceptance of the required Stripe agreements.

addressobjectoptional

The person's address.

address_kanaobjectoptional

The Kana variation of the person's address (Japan only).

address_kanjiobjectoptional

The Kanji variation of the person's address (Japan only).

dobobjectoptional

The person's date of birth.

documentsobjectoptional

Documents that may be submitted to satisfy various informational requests.

emailstringoptional

The person's email address.

expandarray<string>optional

Specifies which fields in the response should be expanded.

first_namestringoptional

The person's first name.

first_name_kanastringoptional

The Kana variation of the person's first name (Japan only).

first_name_kanjistringoptional

The Kanji variation of the person's first name (Japan only).

full_name_aliasesarray<string>optional

A list of alternate names or aliases that the person is known by.

genderstringoptional

The person's gender (International regulations require either "male" or "female").

id_numberstringoptional

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](https://docs.stripe.com/js/tokens/create_token?type=pii). Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance).

id_number_secondarystringoptional

The person's secondary ID number, as appropriate for their country, will be used for enhanced verification checks. In Thailand, this would be the laser code found on the back of an ID card. Instead of the number itself, you can also provide a [PII token provided by Stripe.js](https://docs.stripe.com/js/tokens/create_token?type=pii). Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance).

last_namestringoptional

The person's last name.

last_name_kanastringoptional

The Kana variation of the person's last name (Japan only).

last_name_kanjistringoptional

The Kanji variation of the person's last name (Japan only).

maiden_namestringoptional

The person's maiden name.

metadataobjectoptional

Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.

nationalitystringoptional

The country where the person is a national. Two-letter country code ([ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)), or "XX" if unavailable.

person_tokenstringoptional

A [person token](https://docs.stripe.com/connect/account-tokens), used to securely provide details to the person.

phonestringoptional

The person's phone number.

political_exposurestringoptional

Indicates if the person or any of their representatives, family members, or other closely related persons, declares that they hold or have held an important public job or function, in any jurisdiction.

Allowed:existingnone

registered_addressobjectoptional

The person's registered address.

relationshipobjectoptional

The relationship that this person has with the account's legal entity.

ssn_last_4stringoptional

The last four digits of the person's Social Security number (U.S. only). Changing this value for the account's representative requires that the account re-accept the [terms of service](/api/accounts/object#account_object-tos_acceptance).

us_cfpb_dataobjectoptional

Demographic data related to the person.

verificationobjectoptional

The person's verification status.

2 status codes

200Returns the created person object, including its account, unique identifier, creation time, object type, and submitted person details.

accountstringrequired

The account the person is associated with.

additional_tos_acceptancesobjectoptional

addressobjectoptional

address_kanaobjectoptional

address_kanjiobjectoptional

createdintegerrequired

Time at which the object was created. Measured in seconds since the Unix epoch.

dobobjectoptional

emailstringoptional

The person's email address. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

first_namestringoptional

The person's first name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

first_name_kanastringoptional

The Kana variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

first_name_kanjistringoptional

The Kanji variation of the person's first name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

full_name_aliasesarray<string>optional

A list of alternate names or aliases that the person is known by. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

future_requirementsobjectoptional

genderstringoptional

The person's gender.

idstringrequired

Unique identifier for the object.

id_number_providedbooleanoptional

Whether the person's `id_number` was provided. True if either the full ID number was provided or if only the required part of the ID number was provided (ex. last four of an individual's SSN for the US indicated by `ssn_last_4_provided`).

id_number_secondary_providedbooleanoptional

Whether the person's `id_number_secondary` was provided.

last_namestringoptional

The person's last name. Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

last_name_kanastringoptional

The Kana variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

last_name_kanjistringoptional

The Kanji variation of the person's last name (Japan only). Also available for accounts where [controller.requirement_collection](/api/accounts/object#account_object-controller-requirement_collection) is `stripe`.

maiden_namestringoptional

The person's maiden name.

metadataobjectoptional

Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

nationalitystringoptional

The country where the person is a national.

objectstringrequired

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

Allowed:person

phonestringoptional

The person's phone number.

political_exposurestringoptional

Allowed:existingnone

registered_addressobjectoptional

relationshipobjectoptional

requirementsobjectoptional

ssn_last_4_providedbooleanoptional

Whether the last four digits of the person's Social Security number have been provided (U.S. only).

us_cfpb_dataobjectoptional

Demographic data related to the person.

verificationobjectoptional

defaultReturned when the request cannot be processed; the response contains an API error object with an error type and related details.

errorobjectrequired

Error handling

account must identify the account to associate with the new person and must not exceed 5000 characters. String fields with a maximum length of 5000 characters, including first_name, email, and id_number, must stay within that limit; address.line1 and address.city must not exceed 200 and 100 characters respectively. dob must be a complete object containing day, month, and year, or the allowed empty string.

import { Client } from "acme-sdk";

const client = new Client({
  baseUrl: "https://api.acme.com",
  auth: { bearer: process.env.API_TOKEN },
  retry: {
    maxAttempts: 3,
    retryOn: [
      408,
      425,
      429,
      500,
      502,
      503,
      504,
    ],
    backoffMs: 500,
    maxBackoffMs: 8000,
  },
  timeoutMs: 30000,
});

const result = await client.persons.create({
  account: "example",
  additionalTosAcceptances: {},
  address: {},
  addressKana: {},
  addressKanji: {},
});

{
  "account": 42,
  "additional_tos_acceptances": {
    "account": {
      "date": "2026-01-15T09:00:00Z",
      "ip": "example_value",
      "user_agent": "example_value"
    }
  },
  "address": {
    "city": "example_value",
    "country": "GB",
    "line1": "example_value",
    "line2": "example_value",
    "postal_code": "example_value",
    "state": "example_value"
  },
  "address_kana": {
    "city": "example_value",
    "country": "GB",
    "line1": "example_value",
    "line2": "example_value",
    "postal_code": "example_value",
    "state": "example_value",
    "town": "example_value"
  },
  "address_kanji": {
    "city": "example_value",
    "country": "GB",
    "line1": "example_value",
    "line2": "example_value",
    "postal_code": "example_value",
    "state": "example_value",
    "town": "example_value"
  },
  "created": 1,
  "dob": {
    "day": 1,
    "month": 1,
    "year": 1
  },
  "email": "user@example.com",
  "first_name": "Example Name",
  "first_name_kana": "Example Name",
  "first_name_kanji": "Example Name",
  "full_name_aliases": [
    "Example Name"
  ],
  "future_requirements": {
    "alternatives": [
      {
        "alternative_fields_due": [
          "example_value"
        ],
        "original_fields_due": [
          "example_value"
        ]
      }
    ],
    "currently_due": [
      "example_value"
    ],
    "errors": [
      {
        "code": "external_request",
        "reason": "example_value",
        "requirement": "example_value"
      }
    ],
    "eventually_due": [
      "example_value"
    ],
    "past_due": [
      "example_value"
    ],
    "pending_verification": [
      "example_value"
    ]
  },
  "gender": "example_value",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "id_number_provided": true,
  "id_number_secondary_provided": true,
  "last_name": "Example Name",
  "last_name_kana": "Example Name",
  "last_name_kanji": "Example Name",
  "maiden_name": "Example Name",
  "nationality": "example_value",
  "object": "person",
  "phone": "+44 7700 900123",
  "political_exposure": "existing",
  "registered_address": {
    "city": "example_value",
    "country": "GB",
    "line1": "example_value",
    "line2": "example_value",
    "postal_code": "example_value",
    "state": "example_value"
  },
  "relationship": {
    "authorizer": true,
    "director": true,
    "executive": true,
    "legal_guardian": true,
    "owner": true,
    "percent_ownership": 1,
    "representative": true,
    "title": "Example Title"
  },
  "requirements": {
    "alternatives": [
      {
        "alternative_fields_due": [
          "example_value"
        ],
        "original_fields_due": [
          "example_value"
        ]
      }
    ],
    "currently_due": [
      "example_value"
    ],
    "errors": [
      {
        "code": "external_request",
        "reason": "example_value",
        "requirement": "example_value"
      }
    ],
    "eventually_due": [
      "example_value"
    ],
    "past_due": [
      "example_value"
    ],
    "pending_verification": [
      "example_value"
    ]
  },
  "ssn_last_4_provided": true,
  "us_cfpb_data": {
    "ethnicity_details": {
      "ethnicity": [
        "cuban"
      ],
      "ethnicity_other": "example_value"
    },
    "race_details": {
      "race": [
        "african_american"
      ],
      "race_other": "example_value"
    },
    "self_identified_gender": "example_value"
  },
  "verification": {
    "additional_document": {
      "back": "example_value",
      "details": "example_value",
      "details_code": "example_value",
      "front": "example_value"
    },
    "details": "example_value",
    "details_code": "example_value",
    "document": {
      "back": "example_value",
      "details": "example_value",
      "details_code": "example_value",
      "front": "example_value"
    },
    "status": "active"
  }
}

Request

Response

Errors