Stakeholder Schema
Individuals with ownership or control interests in business entities
The Stakeholder schema defines the structure and properties of stakeholder objects in the Payload API. Stakeholders represent individuals with ownership or control interests in business entities, containing personal information, ownership percentages, government identification, and address details required for compliance and verification in payment processing.
Stakeholder Object Properties
Complete reference for all properties available in the Stakeholder schema
addressobject
The residential address of the stakeholder. PO Boxes are not permitted. This address is used for identity verification, compliance checks, and official correspondence. All address fields (street address, city, state/province, postal code, and country) are required.
address_line_1string
Street address of the address
Max length: 128
address_line_2string
Unit number of the address
Max length: 56
citystring
City of the company
Max length: 56
country_codestring
Country code of the address
Max length: 2
postal_codestring
Postal code of the address
Max length: 7
state_provincestring
State of the address
Max length: 2
associationobject
No description
ownershipobject
Ownership information for this stakeholder, including their equity percentage and duration of ownership. This information is critical for beneficial ownership reporting and compliance requirements. Both fields are required.
percentagenumber (double)
Percentage of equity ownership this stakeholder holds in the company. Should be a number between 0 and 100. The total ownership percentage of all stakeholders must be at least 25% but cannot exceed 100% (except for public corporations and nonprofits where ownership is not required). This value is masked when retrieved for security. Cannot be null and is required.
years_ownedstring
Number of years this stakeholder has held ownership in the company. Used for due diligence and risk assessment purposes. Must be a non-negative number. Cannot be null and is required.
Pattern:
^[0-9]+$rolesobject
Roles assigned to this stakeholder
titlestring
Job title of the stakeholder at the company (e.g., CEO, CFO, President, Owner, Board Member). This helps establish their authority and relationship to the business. Cannot be null and is required.
Max length: 32
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
countryenum[string]Required
The country of residence or citizenship for this stakeholder. Currently supports "US" (United States) or "CA" (Canada). This determines the applicable tax ID type and compliance requirements for the stakeholder.
Values:
US, CAcreated_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
entity_id ID of EntitystringRequiredRead-only
The unique identifier of the business legal entity that this stakeholder is associated with. Links the stakeholder to their parent entity. This field is required and read-only after creation. (ID prefix: ent)
Pattern:
^ent_[A-Za-z0-9]+$govt_idobjectRequired
Government-issued identification information for the stakeholder. Currently only tax IDs (SSN for US, SIN for Canada) are supported. This information is required for identity verification, compliance, and beneficial ownership reporting under applicable regulations.
tax_idobject
Tax identification details for the stakeholder, including both the type and value. The tax ID type is automatically determined based on the stakeholder's country.
typestringRead-only
The type of tax identifier for this individual stakeholder. Automatically determined based on country. For US stakeholders this will be "ssn" (Social Security Number), for Canadian stakeholders this will be "sin" (Social Insurance Number). This field is read-only.
Max length: 24
valuestring
The tax identification number for the stakeholder. Must be exactly 9 digits and a valid SSN format for US stakeholders or SIN format for Canadian stakeholders. This value is masked when retrieved for security. Used for identity verification and compliance. Cannot be null and is required.
Pattern:
^[0-9]+$Max length: 9
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: stkh)
Pattern:
^stkh_[A-Za-z0-9]+$modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
objectenum[string]Read-only
String representing the object type for this resource.
Values:
stakeholderpersonal_informationobjectRequired
Personal information about the stakeholder including their name, contact details, title, and birth date. All fields are required except you can provide either full_name OR both first_name and last_name. This information is used for identity verification, compliance, and KYC (Know Your Customer) requirements.
birth_datestring (date)
Date of birth of the stakeholder. Must be a valid date indicating the person is at least 18 years old. Used for age verification and compliance checks. Cannot be null and is required.
emailstring (email)
Email address of the stakeholder. Must be a valid email format. Used for communication, verification, and compliance purposes. Cannot be null and is required.
Max length: 64
first_namestring
First name (given name) of the stakeholder. Required if full_name is not provided. Either provide first_name and last_name separately, or provide full_name which will be parsed automatically.
Max length: 32
Required if:
Undocumentedfull_namestring
Complete full name of the stakeholder. Required if first_name and last_name are not provided separately. When provided, this will be automatically parsed into first_name and last_name. Must include both a first and last name.
Required if:
Undocumentedlast_namestring
Last name (surname/family name) of the stakeholder. Required if full_name is not provided. Either provide first_name and last_name separately, or provide full_name which will be parsed automatically.
Max length: 32
Required if:
Undocumentedphone_numberstring
Contact phone number for the stakeholder. Must be a valid phone number format. Used for verification and important communications. Cannot be null and is required.
Pattern:
^[0-9]{10}$Max length: 16