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, 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 https://api.increase.com/entities/entity_n8y8tnk2p9339ti393yi \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"

The response includes the validation object:

{
  "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 validated. 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 with a corrected `name`, `tax_identifier`, or both.
`entity_address`	Update an Entity with a corrected `address`.
`beneficial_owner_identity`	Update a Beneficial Owner with corrected identity details, or provide a supplemental identity document.
`beneficial_owner_address`	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 for information on receiving and handling webhooks.

Archiving an Entity

If you can’t access corrected information for an Entity, you should archive it. In order to archive an Entity, you’ll first need to close its Accounts.