Entity Schema
Legal business entities with compliance information and stakeholder details
The Entity schema defines the structure and properties of entity objects in the Payload API. Entities represent legal business entities or individuals in the system, containing comprehensive information about business structure, contact details, stakeholders, and regulatory status required for payment processing and compliance.
Entity Object Properties
Complete reference for all properties available in the Entity schema
addressobject
The physical address where the entity is located or operates. For businesses, this is typically the primary business location. For individuals, this is their residential address. PO Boxes are not permitted. This address is used for legal documentation, compliance verification, and official correspondence. All address fields 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
attrsobject
Custom attributes for extending the resource with additional key-value pairs. Maximum length is 255 characters when serialized.
businessobject
Business-specific information for entities with type "business". This object contains all business-related details including industry category, legal structure, formation details, contact information, and stakeholder ownership. Required for business entities and hidden for individual entities. The required fields within this object vary based on the business structure selected.
Required if:
type=businesscategorystring
The primary industry or business category for this entity. Must be a valid industry key from the supported industries list. This classification helps determine risk assessment, compliance requirements, and applicable regulations.
Max length: 56
formationobject
Information about when and where the business entity was formed. Includes both the formation date and the state or province of incorporation. This information is required for all business entities and is used for verification and compliance purposes.
datestring (date-time)
The date when the business entity was officially formed, incorporated, or registered with government authorities. Used for age verification and compliance checks. Cannot be null.
state_provincestring
The state or province where the legal entity was officially registered or incorporated. For US entities, this is the two-letter state code. For Canadian entities, this is the two-letter province code. Required for compliance and verification purposes.
Max length: 2
primary_contactobject
Information about the primary contact person for this business entity. This person serves as the main point of contact for communications, verification, and business matters. All fields within this object are required.
emailstring (email)
Email address of the primary business contact. Used for important communications, verification, and updates regarding the business entity. Must be a valid email address and cannot be null.
Max length: 64
namestring
Full name of the primary business contact person. This is typically an owner, officer, or authorized representative of the business. Used for verification and communication purposes. Cannot be null.
Max length: 64
public_exchangesobject
Information about stock exchanges and ticker symbols for publicly traded corporations. This object is only applicable and required for entities with structure "public_corp" and contains the primary exchange and corresponding ticker symbols.
Required if:
business[structure]=public_corpprimaryenum[string]
The primary stock exchange where the company is publicly traded. Must be either "NYSE" (New York Stock Exchange) or "NASDAQ". Required for publicly traded corporations.
Values:
NYSE, NASDAQsymbolsobject
Stock ticker symbols for the publicly traded company. Contains the ticker symbol for the primary exchange where the company trades.
nasdaqstring
The stock ticker symbol for this company on the NASDAQ exchange. Required when primary exchange is NASDAQ.
Max length: 5
Required if:
business[public_exchanges][primary]=NASDAQnysestring
The stock ticker symbol for this company on the New York Stock Exchange (NYSE). Required when primary exchange is NYSE.
Max length: 5
Required if:
business[public_exchanges][primary]=NYSEstakeholdersStakeholderarray
List of stakeholders (owners, executives, and beneficial owners) associated with this business entity. Stakeholders must collectively own at least 25% but no more than 100% of the business (except for public corporations and nonprofits). This information is required for compliance, KYC (Know Your Customer), and beneficial ownership reporting. Expanded by default when retrieving the entity.
structureenum[string]
The legal structure of the business entity. Possible values: "llc" (Limited Liability Company), "private_corp" (Private Corporation), "public_corp" (Publicly Traded Corporation), "partnership" (Partnership), "govt" (Government Agency), "trust" (Association/Estate/Trust), "nonprofit" (Tax-Exempt/Nonprofit Organization), or "soleprop" (Sole Proprietorship). This affects tax requirements, compliance rules, and the information required for verification.
Values:
llc, private_corp, public_corp, partnership, govt, trust, nonprofit, solepropwebsitestring
The primary website URL for the business. Must be a valid website address. Used for business verification, compliance checks, and customer reference. Optional but recommended for better transparency and validation.
Max length: 56
countryenum[string]Required
The country where the legal entity is registered or resides. Currently supports "US" (United States) or "CA" (Canada). This determines applicable tax ID types, compliance requirements, and regulatory rules that apply to this entity.
Values:
US, CAcreated_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
idstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: ent)
Pattern:
^ent_[A-Za-z0-9]+$legal_namestringRequired
The official legal name of the entity as registered with government authorities. For individuals, this is typically the full legal name on official documents. For businesses, this is the registered legal business name, which may differ from the DBA (doing business as) name. This name is used for compliance, tax reporting, and legal documentation.
Max length: 56
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:
entityphone_numberstringRequired
Primary contact phone number for the entity. For businesses, this is typically the main business phone number. For individuals, this is their personal contact number. Used for verification, support, and important communications.
Pattern:
^[0-9]{10}$Max length: 16
statusenum[string]
The verification status of this legal entity. Possible values: incomplete (entity information is not fully provided), pending (under review), resubmit (additional information required), rejected (entity did not pass verification), or verified (entity has been successfully verified and approved).
Values:
incomplete, pending, resubmit, rejected, verifiedtax_idobject
Tax identification information for the entity, including both the type and value of the tax ID. Required for individuals and all business structures except sole proprietorships. The tax ID type is automatically determined based on the country and entity type.
Required if:
Undocumentedtypeenum[string]Read-only
The type of tax identifier for this entity. Automatically determined based on country and entity type. Possible values: "ein" (Employer Identification Number for US businesses), "ssn" (Social Security Number for US individuals), or "bn" (Business Number for Canadian businesses). This field is read-only.
Values:
ein, ssn, bnvaluestring
The tax identification number for the entity. Must be exactly 9 digits. For US businesses this is the EIN, for US individuals this is the SSN, and for Canadian businesses this is the BN. This value is masked when retrieved for security. Required for all entities except sole proprietorships.
Pattern:
^[0-9]+$Max length: 9
typeenum[string]Required
The type of legal entity. Must be either "individual" for a person or "business" for a company or organization. This determines which additional fields are required and how the entity is processed for compliance and verification.
Values:
individual, business