The Entity Object

An Entity is one object with three shapes, discriminated by type: individual, business, and sole_prop. All three share the attestation and metadata fields; they differ in their details object and in how they link to other entities. Create with POST /v0/entities and a required Idempotency-Key header (up to 255 characters).

Common Fields (All Three Shapes)

Attribute	Type	Description
`id`	string	Unique Entity ID, prefixed `entity_`. Server-generated, returned on creation.
`client_customer_id`	string (≤64)	Your identifier for the entity. Must be unique — a create with an existing value returns 409. Retrievable via `GET /v0/entities?client_customer_id=…`.
`type`	enum	`individual` · `business` · `sole_prop`. Determines which details object is required.
`intended_roles`	array	Optional synchronous role validation: `account_holder`, `minor_account_holder`, `authorized_signer`, `authorized_user`. All-or-nothing — if any listed role fails validation, the request fails. For `business` / `sole_prop`, pass only `account_holder`. See Roles and Troubleshooting.
`risk_score`	enum	`low` · `medium` · `high` — your risk score, per the mapping you provided Lead. Required for account-holder eligibility.
`kyc_details`	object	`{ result, screened_at }` — result ∈ `pending` / `passed` / `failed`; `screened_at` must be a past timestamp. Your attestation of your KYC/KYB outcome.
`ofac_details`	object	`{ result, screened_at }` — same enum and past-timestamp rule. Your attestation of OFAC screening.
`rfi_details`	object	`{ result, requested_at }` — result ∈ `requested` / `completed`. Leave blank if no RFI has been sent to the customer.
`credit_details`	array	Credit-bureau data: `credit_report_source` (`equifax` / `experian` / `transunion`) and `credit_pulled_at` required; then exactly one of `credit_score` (≤ 850) or `credit_report_non_score_value` (`unestablished` / `frozen` — for credit files without a numeric score). The entity’s `credit_details` is a living record you update over time. The `details.credit.report` on an Application or Account is a point-in-time capture of the pull used for that credit decision, so the two can legitimately differ.
`role_details`	array	Response-only. Per role: `name`, `status` (`active` / `inactive`), and `criteria_details[]` of `{ entity_id, failed_checks[] }` naming exactly which checks fail and on which entity — including child entities. The `minor_account_holder` entry appears only where the role is available to the program; when it is not, the entry is omitted rather than returned inactive. How to read it: Troubleshooting.
`metadata`	object	Arbitrary key-value pairs.

`individual_details` (Required for `individual`)

Required within it: first_name, last_name, and identification_details. First name must be at least 1 alphanumeric character. Last name must be at least 2.

Attribute	Notes
`first_name` / `middle_name` / `last_name` / `preferred_first_name`	Legal names; preferred first name optional.
`date_of_birth`	`YYYY-MM-DD`. Account holders and authorized signers must be 18+; `minor_account_holder` requires 16–17 (Roles).
`occupation`	Optional.
`contact_methods`	Array of `{ type: email, email }` or `{ type: phone_number, phone_number }`. Emails must be real-world `local-part@domain.tld` forms; phone numbers must follow E.123 (`+` country code with spacing — Workflow).
`address_details`	`physical_address`, `mailing_address`, `other_addresses[]` — see Address Rules below.
`identification_details`	US vs. non-US — see Identification below.
`additional_documents`	Optional supporting documents: `bank_statement`, `utility_bills`, `proof_of_address`, `investigation_report`, `financial_statement`, `public_records`, `adverse_media`, `id_selfie`, `other` (with `description` required for `other`).

`business_details` (Required for `business` and `sole_prop`)

Required within it: name (≥2 characters), identification_details, and address_details.

Attribute	Notes
`type`	`corporation` · `partnership` · `sole_prop` · `llc` · `trust` · `cooperative` · `other`. A `business` entity cannot use `sole_prop` as its business type; a `sole_prop` entity must.
`name` / `doing_business_as`	Legal name; DBA if operating under a different name.
`industry`	NAICS code(s), 2–6 digits, 2022 reference files.
`gross_annual_revenue` + `currency_code`	Prior fiscal year revenue; ISO 4217.
`website`	Must start with `http://` or `https://`.
`contact_methods` / `address_details` / `identification_details` / `additional_documents`	As for individuals; business identification-document types differ (formation documents, certificates of good standing, etc.).

Linkage Objects Resolving Ownership to People

Business-family entities link to individual entities rather than embedding their data — create the individuals first (Workflow), then reference them:

Object	On	Required fields	Notes
`beneficial_owners[]`	`business`	`entity_id`	Plus optional `ownership_percentage` (0–100.00 or 0–1.00 decimal) and `relationship_established_at`. Who must be listed, the 25% threshold, and the drill-down rule: Beneficial Ownership Requirements. An empty array is a valid submission when there are genuinely no qualifying owners.
`control_persons[]`	`business`	`entity_id`, `title`	At least one is required for account-holder eligibility (`CheckControlPersonExists`).
`sole_proprietor`	`sole_prop` (required)	`entity_id`	The individual behind the sole proprietorship.

Each referenced individual must meet authorized-signer data requirements — a child entity failing its checks makes the parent’s role inactive, with criteria_details pointing at the child’s entity_id (Troubleshooting).

Identification for US and Non-US Entities

The identification_details object is discriminated by whether the entity has a US tax identification:

us_entity — tax_identification with type (ssn / itin / ein) and a 9-digit value. Rules: SSNs must not start with 9 (ITINs mistakenly reported as SSNs are the most common failure); EINs begin 00–99; ITINs begin with 9. Individuals: ssn or itin. Businesses: ein — except single-member LLCs with no EIN, where ssn or itin may be used. Sole props: any of the three.
non_us_entity — at least one government-verified identification_documents[] entry: type, identification_number, issuing_country required (plus issuing_state for US-issued, expiration_date, description when type is other). Individual document types: drivers_license, state_or_provincial_id, passport, permanent_residency_id, military_id, national_id, matriculate_id, other. Business types: tax_certificate, tax_returns, partnership_agreement, certificate_of_good_standing, formation_document, proof_of_place_on_stock_exchange, other.

Address Rules

line_1 is the full base address — street number and street name together (or the local equivalent). Address rules protect the structure of the address, not its character set. However you collect address components from your users, combine them into line_1 before sending: do not split the primary street address across lines, do not put only the number in line 1, and never pad line 1 to satisfy validation. line_2 is only for sub-premise information (apartment, unit, suite, floor, building, care-of) — blank otherwise. city and country (ISO 3166-1 alpha-2) are required; US addresses also require a valid USPS state code and a 5- or 9-digit postal_code. Physical addresses must not be P.O. boxes, registered-agent addresses, or in prohibited countries.

Example Entity Object

{
  "id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d",
  "client_customer_id": "cust-000482",
  "created_at": "2026-06-11T14:22:05Z",
  "updated_at": "2026-06-11T14:22:05Z",
  "type": "individual",
  "intended_roles": ["account_holder"],
  "risk_score": "low",
  "individual_details": {
    "first_name": "Amanda",
    "last_name": "Reyes",
    "date_of_birth": "1992-02-15",
    "contact_methods": [
      { "type": "email", "email": "amanda@example.com" }
    ],
    "address_details": {
      "physical_address": {
        "line_1": "123 Main St.",
        "line_2": "Apt 25",
        "city": "Denver",
        "state": "CO",
        "postal_code": "80014",
        "country": "US"
      }
    },
    "identification_details": {
      "type": "us_entity",
      "tax_identification": { "type": "ssn", "value": "234567890" }
    }
  },
  "kyc_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" },
  "ofac_details": { "result": "passed", "screened_at": "2026-06-11T14:20:00Z" },
  "role_details": [
    {
      "name": "account_holder",
      "status": "active",
      "criteria_details": [
        { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] }
      ]
    },
    {
      "name": "authorized_signer",
      "status": "active",
      "criteria_details": [
        { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] }
      ]
    },
    {
      "name": "authorized_user",
      "status": "active",
      "criteria_details": [
        { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": [] }
      ]
    },
    {
      "name": "minor_account_holder",
      "status": "inactive",
      "criteria_details": [
        { "entity_id": "entity_7RwQ2mK9pL4xT1vN8jS5bA3cG6d", "failed_checks": ["CheckDateOfBirthAboveMaximum"] }
      ]
    }
  ],
  "metadata": {}
}

Full request/response schemas: Create an Entity · Update an Entity.

Banking Infrastructure

Lending & Receivables

Payment Rails

Customers & Accounts

Network Settlement

Common Fields (All Three Shapes)

`individual_details` (Required for `individual`)

`business_details` (Required for `business` and `sole_prop`)

Linkage Objects Resolving Ownership to People

Identification for US and Non-US Entities

Address Rules

Example Entity Object

​Common Fields (All Three Shapes)

​individual_details (Required for individual)

​business_details (Required for business and sole_prop)

​Linkage Objects Resolving Ownership to People

​Identification for US and Non-US Entities

​Address Rules

​Example Entity Object

Common Fields (All Three Shapes)

`individual_details` (Required for `individual`)

`business_details` (Required for `business` and `sole_prop`)

Linkage Objects Resolving Ownership to People

Identification for US and Non-US Entities

Address Rules

Example Entity Object