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 details about an Entity's KYC journey are in the validation object. The status field indicates the lifecycle of the review.


`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.

{
  "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 with a corrected `name` and/or tax identifier (for a corporation, `corporation.legal_identifier`).
`entity_address`	Update an Entity with a corrected `address` (for a corporation, `corporation.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`.

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 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.

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 to set the validation directly:

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.