# Entity validation

#### Increase automatically validates entity information to ensure it meets compliance requirements.

---

If you move money on behalf of your customers, it's important to collect and validate their information. This is sometimes called Know Your Customer, or "KYC." For some programs, Increase's APIs are an important tool in the KYC process.

When you create or update an [Entity](/documentation/api/entities), Increase validates the submitted information. This includes verifying tax identifiers, addresses, and beneficial owner details. The validation process runs automatically in the background, and results are available through the `validation` attribute on the Entity.

## Accessing validation status

The validation status is available as a `validation` object on the Entity. You can retrieve it when fetching an individual entity or listing entities:

```curl
curl https://api.increase.com/entities/entity_n8y8tnk2p9339ti393yi \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

The details about an Entity's KYC journey are in the `validation` object. The `status` field indicates the lifecycle of the review.

Entity validation status lifecycle

|           |                                                                                                                                                      |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pending` | The submitted information is still being validated. Validation runs promptly, but not instantly. It will usually take a minute or two to transition. |
| `valid`   | The submitted information passed validation. No action is required.                                                                                  |
| `invalid` | Additional information is required. The `issues` array describes what needs to be corrected.                                                         |

If the status is `invalid`, the `issues` array will describe what actions to take.

```json
{
  "id": "entity_n8y8tnk2p9339ti393yi",
  // ...
  "validation": {
    "status": "invalid",
    "issues": [
      {
        "category": "entity_address",
        "entity_address": {
          "reason": "mailbox_address"
        }
      },
      {
        "category": "beneficial_owner_identity",
        "beneficial_owner_identity": {
          "beneficial_owner_id": "entity_beneficial_owner_q8x9h2k3p1m4n5"
        }
      }
    ]
  }
}
```

## Validation issues

Each entry in the `issues` array has a `category` indicating the type of problem. Increase may add additional possible values for this enum over time; your application should be able to handle such additions gracefully.

In addition to the `category`, each issue includes a detail object named after its category. For example, the beneficial owner issues include the `beneficial_owner_id` identifying which beneficial owner to update.

| Category                    | Description                                                                                                                                                                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_tax_identifier`     | The entity's tax identifier could not be verified. Update the entity's name, tax id, or both.                                                                                                                                                |
| `entity_address`            | The entity's address could not be validated. PO Boxes and similar mailbox addresses are not acceptable.                                                                                                                                      |
| `beneficial_owner_identity` | A beneficial owner's identity could not be verified. Double check the name, address, and identification number for the beneficial owner. You can also provide a second identification source, like a scan of a passport or driver's license. |
| `beneficial_owner_address`  | A beneficial owner's address could not be validated. PO Boxes and similar mailbox addresses are not acceptable.                                                                                                                              |

## Making updates

You can make corrections and changes to an Entity via API and Dashboard. On the page for an Entity in the Dashboard, you'll see the same issue categories and descriptions listed above, along with a button to fix each one. We recommend fixing the first several issues via the Dashboard so that you build a familiarity with the types of flows and data that require remediation. Then, you can implement the same flows in your own application using the API.

Each issue category maps to a specific API call:

| Category                    | API action                                                                                                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_tax_identifier`     | [Update an Entity](/documentation/api/entities#update-an-entity) with a corrected `name` and/or tax identifier (for a corporation, `corporation.legal_identifier`).       |
| `entity_address`            | [Update an Entity](/documentation/api/entities#update-an-entity) with a corrected `address` (for a corporation, `corporation.address`).                                   |
| `beneficial_owner_identity` | [Update a Beneficial Owner](/documentation/api/beneficial-owners#update-a-beneficial-owner) with corrected identity details, or provide a supplemental identity document. |
| `beneficial_owner_address`  | [Update a Beneficial Owner](/documentation/api/beneficial-owners#update-a-beneficial-owner) with a corrected `address`.                                                   |

When updating an Entity, these fields are nested under the entity's structure object — `corporation`, `natural_person`, `trust`, or `government_authority` — matching how the Entity was created. For example, you correct a corporation's address under `corporation.address`.

After making updates, the validation `status` will reset to `pending`, and the entity is re-evaluated.

## Webhooks

When an entity's validation status changes, Increase sends an `entity.updated` webhook. You can use this to monitor validation progress and take action when issues are detected.

See [Webhooks](/documentation/webhooks) for information on receiving and handling webhooks.

## Archiving an Entity

If you can't access corrected information for an Entity, you should [archive](/documentation/api/entities#archive-an-entity) it. In order to archive an Entity, you'll first need to [close](/documentation/api/accounts#close-an-account) its Accounts.

## Sandbox

In the sandbox environment, validations don't run automatically. To exercise your application's handling of each status and issue category, use [Simulate the status for an Entity's validation](/documentation/api/entities#sandbox-simulate-validation-of-an-entity) to set the validation directly:

```curl
curl -X POST \
  --url "https://sandbox.increase.com/simulations/entities/${ENTITY_ID}/update_validation" \
  -H "Authorization: Bearer ${INCREASE_SANDBOX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "issues": [
      { "category": "entity_tax_identifier" }
    ]
  }'
```

Each call replaces the Entity's validation. The resulting status is derived from the `issues` you send: an empty `issues` array produces a `valid` status, and a non-empty array produces an `invalid` status. The `beneficial_owner_identity` and `beneficial_owner_address` issues require a corporation Entity. The same simulation is available on the Entity detail page in the Sandbox Dashboard.