# Beneficial Owners
> Beneficial owners are the individuals who control or own 25% or more of a `corporation` entity. Beneficial owners are always people, and never organizations. Generally, you will need to submit between 1 and 5 beneficial owners for every `corporation` entity. You should update and archive beneficial owners for a corporation entity as their details change.

## The Beneficial Owner object
### Example
```json
{
  "company_title": "CEO",
  "created_at": "2020-01-31T23:59:59Z",
  "entity_id": "entity_n8y8tnk2p9339ti393yi",
  "id": "entity_beneficial_owner_vozma8szzu1sxezp5zq6",
  "idempotency_key": null,
  "individual": {
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "line2": null,
      "state": "NY",
      "zip": "10045"
    },
    "date_of_birth": "1970-01-31",
    "identification": {
      "method": "social_security_number",
      "number_last4": "1120"
    },
    "name": "Ian Crease"
  },
  "prongs": [
    "control",
    "ownership"
  ],
  "type": "entity_beneficial_owner"
}
```
### Attributes
- `company_title` (string, nullable)
  This person's role or title within the entity.

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the Beneficial Owner was created.

- `entity_id` (string)
  The identifier of the Entity to which this beneficial owner belongs.

- `id` (string)
  The identifier of this beneficial owner.

- `idempotency_key` (string, nullable)
  The idempotency key you chose for this object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

- `individual` (dictionary)
  Personal details for the beneficial owner.

  - `individual.address` (dictionary)
    The person's address.

      - `individual.address.city` (string, nullable)
        The city, district, town, or village of the address.

      - `individual.address.country` (string)
        The two-letter ISO 3166-1 alpha-2 code for the country of the address.

      - `individual.address.line1` (string)
        The first line of the address.

      - `individual.address.line2` (string, nullable)
        The second line of the address.

      - `individual.address.state` (string, nullable)
        The two-letter United States Postal Service (USPS) abbreviation for the US state, province, or region of the address.

      - `individual.address.zip` (string, nullable)
        The ZIP or postal code of the address.

  - `individual.date_of_birth` (string)
    The person's date of birth in YYYY-MM-DD format.

  - `individual.identification` (dictionary, nullable)
    A means of verifying the person's identity.

      - `individual.identification.method` (enum)
        A method that can be used to verify the individual's identity.
        Cases:
        * `social_security_number` (A social security number.)
        * `individual_taxpayer_identification_number` (An individual taxpayer identification number (ITIN).)
        * `passport` (A passport number.)
        * `drivers_license` (A driver's license number.)
        * `other` (Another identifying document.)

      - `individual.identification.number_last4` (string)
        The last 4 digits of the identification number that can be used to verify the individual's identity.

  - `individual.name` (string)
    The person's legal name.

- `prongs` (array of enums)
  Why this person is considered a beneficial owner of the entity.
  Cases:
  * `ownership` (A person with 25% or greater direct or indirect ownership of the entity.)
  * `control` (A person who manages, directs, or has significant control of the entity.)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `entity_beneficial_owner`.

## List Beneficial Owners
GET /entity_beneficial_owners

### Example
```curl
curl \
  --url "${INCREASE_URL}/entity_beneficial_owners?entity_id=entity_n8y8tnk2p9339ti393yi" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `entity_id` (string, required)
  The identifier of the Entity to list beneficial owners for. Only `corporation` entities have beneficial owners.

- `idempotency_key` (string, optional)
  Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).

### Returns a Beneficial Owner List object:
```json
{
  "data": [
    {
      "company_title": "CEO",
      "created_at": "2020-01-31T23:59:59Z",
      "entity_id": "entity_n8y8tnk2p9339ti393yi",
      "id": "entity_beneficial_owner_vozma8szzu1sxezp5zq6",
      "idempotency_key": null,
      "individual": {
        "address": {
          "city": "New York",
          "country": "US",
          "line1": "33 Liberty Street",
          "line2": null,
          "state": "NY",
          "zip": "10045"
        },
        "date_of_birth": "1970-01-31",
        "identification": {
          "method": "social_security_number",
          "number_last4": "1120"
        },
        "name": "Ian Crease"
      },
      "prongs": [
        "control",
        "ownership"
      ],
      "type": "entity_beneficial_owner"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Create a Beneficial Owner
POST /entity_beneficial_owners

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/entity_beneficial_owners" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "company_title": "CEO",
    "entity_id": "entity_n8y8tnk2p9339ti393yi",
    "individual": {
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "33 Liberty Street",
        "state": "NY",
        "zip": "10045"
      },
      "date_of_birth": "1970-01-31",
      "identification": {
        "method": "social_security_number",
        "number": "078051120"
      },
      "name": "Ian Crease"
    },
    "prongs": [
      "control"
    ]
  }'
```

### Body Parameters
- `company_title` (string, optional)
  This person's role or title within the entity.

- `entity_id` (string, required)
  The identifier of the Entity to associate with the new Beneficial Owner.

- `individual` (dictionary, required)
  Personal details for the beneficial owner.

  - `individual.address` (dictionary, required)
    The individual's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.

      - `individual.address.city` (string, required)
        The city, district, town, or village of the address.

      - `individual.address.country` (string, required)
        The two-letter ISO 3166-1 alpha-2 code for the country of the address.

      - `individual.address.line1` (string, required)
        The first line of the address. This is usually the street number and street.

      - `individual.address.line2` (string, optional)
        The second line of the address. This might be the floor or room number.

      - `individual.address.state` (string, optional)
        The two-letter United States Postal Service (USPS) abbreviation for the US state, province, or region of the address. Required in certain countries.

      - `individual.address.zip` (string, optional)
        The ZIP or postal code of the address. Required in certain countries.

  - `individual.confirmed_no_us_tax_id` (boolean, optional)
    The identification method for an individual can only be a passport, driver's license, or other document if you've confirmed the individual does not have a US tax id (either a Social Security Number or Individual Taxpayer Identification Number).

  - `individual.date_of_birth` (string, required)
    The person's date of birth in YYYY-MM-DD format.

  - `individual.identification` (dictionary, required)
    A means of verifying the person's identity.

      - `individual.identification.drivers_license` (dictionary, optional)
        Information about the United States driver's license used for identification. Required if `method` is equal to `drivers_license`.

            - `individual.identification.drivers_license.back_file_id` (string, optional)
              The identifier of the File containing the back of the driver's license.

            - `individual.identification.drivers_license.expiration_date` (string, required)
              The driver's license's expiration date in YYYY-MM-DD format.

            - `individual.identification.drivers_license.file_id` (string, required)
              The identifier of the File containing the front of the driver's license.

            - `individual.identification.drivers_license.state` (string, required)
              The state that issued the provided driver's license.

      - `individual.identification.method` (enum, required)
        A method that can be used to verify the individual's identity.
        Cases:
        * `social_security_number` (A social security number.)
        * `individual_taxpayer_identification_number` (An individual taxpayer identification number (ITIN).)
        * `passport` (A passport number.)
        * `drivers_license` (A driver's license number.)
        * `other` (Another identifying document.)

      - `individual.identification.number` (string, required)
        An identification number that can be used to verify the individual's identity, such as a social security number.

      - `individual.identification.other` (dictionary, optional)
        Information about the identification document provided. Required if `method` is equal to `other`.

            - `individual.identification.other.back_file_id` (string, optional)
              The identifier of the File containing the back of the document. Not every document has a reverse side.

            - `individual.identification.other.country` (string, required)
              The two-character ISO 3166-1 code representing the country that issued the document (e.g., `US`).

            - `individual.identification.other.description` (string, required)
              A description of the document submitted.

            - `individual.identification.other.expiration_date` (string, optional)
              The document's expiration date in YYYY-MM-DD format.

            - `individual.identification.other.file_id` (string, required)
              The identifier of the File containing the front of the document.

      - `individual.identification.passport` (dictionary, optional)
        Information about the passport used for identification. Required if `method` is equal to `passport`.

            - `individual.identification.passport.country` (string, required)
              The two-character ISO 3166-1 code representing the country that issued the document (e.g., `US`).

            - `individual.identification.passport.expiration_date` (string, required)
              The passport's expiration date in YYYY-MM-DD format.

            - `individual.identification.passport.file_id` (string, required)
              The identifier of the File containing the passport.

  - `individual.name` (string, required)
    The person's legal name.

- `prongs` (array of enums, required)
  Why this person is considered a beneficial owner of the entity. At least one option is required, if a person is both a control person and owner, submit an array containing both.
  Cases:
  * `ownership` (A person with 25% or greater direct or indirect ownership of the entity.)
  * `control` (A person who manages, directs, or has significant control of the entity.)

## Retrieve a Beneficial Owner
GET /entity_beneficial_owners/{entity_beneficial_owner_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/entity_beneficial_owners/entity_beneficial_owner_vozma8szzu1sxezp5zq6" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `entity_beneficial_owner_id` (string, required)
  The identifier of the Beneficial Owner to retrieve.

## Update a Beneficial Owner
PATCH /entity_beneficial_owners/{entity_beneficial_owner_id}

### Example
```curl
curl -X "PATCH" \
  --url "${INCREASE_URL}/entity_beneficial_owners/entity_beneficial_owner_vozma8szzu1sxezp5zq6" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "address": {
      "city": "New York",
      "country": "US",
      "line1": "33 Liberty Street",
      "line2": "Unit 2",
      "state": "NY",
      "zip": "10045"
    }
  }'
```
### Path Parameters
- `entity_beneficial_owner_id` (string, required)
  The identifier of the Beneficial Owner to update.

### Body Parameters
- `address` (dictionary, optional)
  The individual's physical address. Mail receiving locations like PO Boxes and PMB's are disallowed.

  - `address.city` (string, required)
    The city, district, town, or village of the address.

  - `address.country` (string, required)
    The two-letter ISO 3166-1 alpha-2 code for the country of the address.

  - `address.line1` (string, required)
    The first line of the address. This is usually the street number and street.

  - `address.line2` (string, optional)
    The second line of the address. This might be the floor or room number.

  - `address.state` (string, optional)
    The two-letter United States Postal Service (USPS) abbreviation for the US state, province, or region of the address. Required in certain countries.

  - `address.zip` (string, optional)
    The ZIP or postal code of the address. Required in certain countries.

- `confirmed_no_us_tax_id` (boolean, optional)
  The identification method for an individual can only be a passport, driver's license, or other document if you've confirmed the individual does not have a US tax id (either a Social Security Number or Individual Taxpayer Identification Number).

- `identification` (dictionary, optional)
  A means of verifying the person's identity.

  - `identification.drivers_license` (dictionary, optional)
    Information about the United States driver's license used for identification. Required if `method` is equal to `drivers_license`.

      - `identification.drivers_license.back_file_id` (string, optional)
        The identifier of the File containing the back of the driver's license.

      - `identification.drivers_license.expiration_date` (string, required)
        The driver's license's expiration date in YYYY-MM-DD format.

      - `identification.drivers_license.file_id` (string, required)
        The identifier of the File containing the front of the driver's license.

      - `identification.drivers_license.state` (string, required)
        The state that issued the provided driver's license.

  - `identification.method` (enum, required)
    A method that can be used to verify the individual's identity.
    Cases:
    * `social_security_number` (A social security number.)
    * `individual_taxpayer_identification_number` (An individual taxpayer identification number (ITIN).)
    * `passport` (A passport number.)
    * `drivers_license` (A driver's license number.)
    * `other` (Another identifying document.)

  - `identification.number` (string, required)
    An identification number that can be used to verify the individual's identity, such as a social security number.

  - `identification.other` (dictionary, optional)
    Information about the identification document provided. Required if `method` is equal to `other`.

      - `identification.other.back_file_id` (string, optional)
        The identifier of the File containing the back of the document. Not every document has a reverse side.

      - `identification.other.country` (string, required)
        The two-character ISO 3166-1 code representing the country that issued the document (e.g., `US`).

      - `identification.other.description` (string, required)
        A description of the document submitted.

      - `identification.other.expiration_date` (string, optional)
        The document's expiration date in YYYY-MM-DD format.

      - `identification.other.file_id` (string, required)
        The identifier of the File containing the front of the document.

  - `identification.passport` (dictionary, optional)
    Information about the passport used for identification. Required if `method` is equal to `passport`.

      - `identification.passport.country` (string, required)
        The two-character ISO 3166-1 code representing the country that issued the document (e.g., `US`).

      - `identification.passport.expiration_date` (string, required)
        The passport's expiration date in YYYY-MM-DD format.

      - `identification.passport.file_id` (string, required)
        The identifier of the File containing the passport.

- `name` (string, optional)
  The individual's legal name.

## Archive a Beneficial Owner
POST /entity_beneficial_owners/{entity_beneficial_owner_id}/archive

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/entity_beneficial_owners/entity_beneficial_owner_vozma8szzu1sxezp5zq6/archive" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `entity_beneficial_owner_id` (string, required)
  The identifier of the Beneficial Owner to archive.