# 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 response includes the `validation` object:

```json
{
  "id": "entity_n8y8tnk2p9339ti393yi",
  // ...
  "validation": {
    "status": "invalid",
    "issues": [
      {
        "category": "entity_address"
      }
    ]
  }
}
```

## Validation issues

When the status is `invalid`, the `issues` array contains details about what needs to be corrected. Each issue 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.

| 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`, `legal_identifier`, or both.                                                    |
| `entity_address`            | [Update an Entity](/documentation/api/entities#update-an-entity) with a corrected `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`.                                                   |

## 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. `issues` may only be set when `status` is `invalid`, and `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.