# Person entity object

An entity represents a person or organization possessing separate and distinct legal rights. You will create entities for each of your customers or users. An entity is required to create a bank account or a loan object. Read about [entities in our data model](/data-models/entity) for more information.

### Object Parameters

- `collected_at` `object` — Field collection timestamps, keyed by field path (for example, `first_name` or `ssn`). Omitted when no timestamps are recorded.
- `documents` `array of objects` — List of documents which are uploaded with the Submit Document API
  - `created_at` `date-time` — Timestamp at which the document was created.
  - `description` `string` — Description of the uploaded document.
  - `document_id` `string` — Unique identifier of the document.
  - `entity_id` `string` — Unique identifier of the entity the document belongs to.
- `id` `string` — Unique identifier for the object
- `is_root` `boolean` — Whether this entity is going to be a root entity of the platform. Root entities have special requirements and validation rules.
- `last_screened_at` `date-time` — The timestamp at which the entity was last screened for compliance.
- `name` `string` — Display name of the entity, derived from person or business details.
- `person_details` `object` — Person details for person entities. Present on single-entity responses, omitted in list responses.
  - `address` `object` — Addresses need to adhere to character validation, as addresses are used across multiple payment rails. Characters are validated according to the [Fedwire character validation](/wire#valid-characters-permitted).
    - `city` `string` — City name
    - `country_code` `string` — Two-letter ISO 3166-1 alpha-2 country code (e.g. `US`)
    - `line_1` `string` — Street address line 1
    - `line_2` `string` — Street address line 2
    - `postal_code` `string` — Postal or ZIP code
    - `state` `string` — State or province
  - `country_of_citizenship` `string` — Country of citizenship of the individual. Country of citizenship does not need to match the issuing country of an identity document. ISO 3166-1 Alpha-2 Country Code (e.g., `US`, `FR`, `UK`, `DE`, ...).
  - `date_of_birth` `string` — Date of birth (`YYYY-MM-DD`)
  - `drivers_license` `object` — Driver's License Details. Passport, Driver's License or National ID is required for non U.S. citizens. When left blank, the Passport field returns an empty object ( ) and the Driver's License and National ID fields return `null`.
    - `country_code` `string` — Two-letter ISO 3166-1 alpha-2 country code of the issuing country
    - `number` `string` — Driver's license number
  - `email` `string` — Email of the individual. Optional, but highly encouraged as it will increase likelihood of an automated verification. When left blank, the Email field returns an empty string (`""`).
  - `employment_status` `string` — Employment status of the individual.
  - `expected_payment_rails` `string` — Expected transaction types for the account.
  - `first_name` `string` — First name of the legal person. Must adhere to [Fedwire character validation](/wire#valid-characters-permitted).
  - `income` `array of numbers` — Estimated pre-tax annual income. Accepts an array to allow passing income ranges.
  - `is_beneficial_owner` `boolean` — Boolean value which specifies if this person is a designated beneficial owner.
  - `is_control_person` `boolean` — Boolean value which specifies if this person is a designated control person.
  - `is_high_risk` `boolean` — Indicates whether the entity has been identified as high risk based on compliance screening
  - `job_title` `string` — Job title of the beneficial owner or control person.
  - `last_name` `string` — Last name of the legal person. Must adhere to [Fedwire character validation](/wire#valid-characters-permitted).
  - `makes_international_payments` `boolean` — Indicates whether the individual expects to make international payments.
  - `middle_name` `string` — Middle name of the legal person. Must adhere to [Fedwire character validation](/wire#valid-characters-permitted).
  - `national_id` `object` — National ID Details. Passport, Driver's License or National ID is required for non U.S. citizens. When left blank, the Passport field returns an empty object ( ) and the Driver's License and National ID fields return `null`.
    - `country_code` `string` — Two-letter ISO 3166-1 alpha-2 country code of the issuing country
    - `number` `string` — National ID number
  - `occupation` `string` — Industry of employment or occupation of the individual.
  - `ownership_percentage` `integer` — Percentage ownership, specified as an integer, of the beneficial owner
  - `passport` `object` — Passport Details. Passport, Driver's License or National ID is required for non U.S. citizens. When left blank, the Passport field returns an empty object ( ) and the Driver's License and National ID fields return `null`.
    - `country_code` `string` — Two-letter ISO 3166-1 alpha-2 country code of the issuing country
    - `number` `string` — Passport number
  - `pep_status` `string` — Politically Exposed Person screening status. Allowed values: `not_checked`, `no`, `yes`, `potential`.
  - `phone_number` `string` — Phone number of the individual in the E.164 format. Optional, but highly encouraged as it will increase likelihood of an automated verification. When left blank, the phone number field returns an empty string (`""`).
  - `purpose_of_account` `array of strings` — Intended use of the account.
  - `role` `string` — Individual's role or job title at their place of employment.
  - `source_of_income` `array of strings` — Sources of income for the individual.
  - `ssn` `string` — Social Security Number. SSN is required for U.S. citizens. ITIN may be shared in place of SSN. If SSN is provided, country of citizenship is not required. When left blank (i.e., for non-U.S. citizens) the SSN field returns an empty string (`""`).
- `requires_screening` `boolean` — Whether the entity requires additional screening before it can be verified.
- `review_reasons` `array of strings` — List of reasons the entity is in `Manual_Review`.
- `search_metadata` `object` — Search-specific metadata returned when a query is provided.
  - `highlights` `object` — Matched field fragments with highlighted terms
  - `score` `number` — OpenSearch relevance score
- `type` `string` — Type of entity. `PERSON` for a person entity. `BUSINESS` for a business entity.
- `verification_status` `string` — Current status of the entity verification. Can be `UNVERIFIED`, `PENDING`, `MANUAL_REVIEW`, `VERIFIED`, or `DENIED`.

**Response 200**

```json
{
  "collected_at": {},
  "documents": [
    {
      "created_at": "2024-01-15T09:30:00Z",
      "description": "Example description",
      "document_id": "docu_2Q1ctiJm1NypVqCt8UBC8e4xTfH",
      "entity_id": "enti_2Q1ctiJm1NypVqCt8UBC8e4xTfH"
    }
  ],
  "id": "item_2Q1ctiJm1NypVqCt8UBC8e4xTfH",
  "is_root": false,
  "last_screened_at": "2024-01-15T09:30:00Z",
  "name": "Example name",
  "person_details": {
    "address": {
      "city": "San Francisco",
      "country_code": "US",
      "line_1": "101 Market St",
      "line_2": "Suite 1913",
      "postal_code": "94105",
      "state": "CA"
    },
    "country_of_citizenship": "US",
    "date_of_birth": "1985-08-04",
    "drivers_license": {
      "number": "A12345678",
      "country_code": "US"
    },
    "email": "oliver@example.com",
    "employment_status": "employed",
    "expected_payment_rails": "ach",
    "first_name": "Oliver",
    "income": [],
    "is_beneficial_owner": false,
    "is_control_person": false,
    "is_high_risk": false,
    "job_title": "Chief Executive Officer",
    "last_name": "Hockey",
    "makes_international_payments": false,
    "middle_name": "Smith",
    "national_id": {
      "number": "A12345678",
      "country_code": "US"
    },
    "occupation": "Software Engineer",
    "ownership_percentage": 0,
    "passport": {
      "number": "A12345678",
      "country_code": "US"
    },
    "pep_status": "not_checked",
    "phone_number": "+15555555555",
    "purpose_of_account": [
      "business_operations"
    ],
    "role": "owner",
    "source_of_income": [
      "employment"
    ],
    "ssn": "565438976"
  },
  "requires_screening": false,
  "review_reasons": [
    null
  ],
  "search_metadata": {
    "highlights": {},
    "score": 0
  },
  "type": "PERSON",
  "verification_status": "pending"
}
```