> ## Documentation Index
> Fetch the complete documentation index at: https://docs.equalsmoney.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding webhooks

> After submitting an onboarding application, learn which webhooks you'll receive and in what order.

# Onboarding webhooks

After submitting a personal or business onboarding application, the review process is asynchronous. You'll receive webhook notifications at each stage as your application progresses through verification and approval.

Use the `applicationId` included in each webhook payload to link events back to the original onboarding submission.

<Tip>
  When creating webhooks for onboarding event types, always omit the `accountId` field. These are platform-level events that fire before an account has been created. Including `accountId` scopes the webhook to a specific account, meaning you will never receive onboarding notifications. See [creating a webhook](/pages/webhooks/tutorial/step3) for examples.
</Tip>

<Info>
  Make sure you've [set up your webhooks](/pages/webhooks/how-it-works) and subscribed to the relevant event types before submitting an application.
</Info>

## Webhook flow overview

| Order | Webhook event                                         | Description                                  | Always received?                                    |
| ----- | ----------------------------------------------------- | -------------------------------------------- | --------------------------------------------------- |
| 1     | `IdentityVerificationRequest`                         | Identity verification link for the applicant | Conditional - Managed by Equals model only          |
| 2     | `KycInformationRequested` / `KybInformationRequested` | Additional information required              | Conditional - only if further information is needed |
| 3     | `ApplicationStatusUpdated`                            | Application approved or declined             | Always                                              |
| 4     | `AccountActivated`                                    | Account is live and ready to trade           | Only if approved                                    |

***

## Step 1: Identity verification

If your integration uses the **Managed by Equals** KYC model, you'll receive an `IdentityVerificationRequest` webhook when identity verification is required.

This event includes an `actionUrl` - a link for the applicant to complete their identity verification session (liveness check and document upload). You should pass this URL to your applicant so they can complete the process.

**Key fields:**

| Field                | Description                                                                                                                                                     |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `applicationId`      | The ID of the application this webhook relates to                                                                                                               |
| `associatedPersonId` | The ID of the associated person who needs to verify their identity. `null` for personal applications; populated for associated people on business applications. |
| `name`               | Full name of the person who needs to complete identity verification                                                                                             |
| `email`              | Email address of the person who needs to complete identity verification                                                                                         |
| `actionUrl`          | URL for the applicant to complete their identity verification session                                                                                           |
| `eventTime`          | ISO 8601 timestamp of when the event was created                                                                                                                |

<Info>
  This webhook is only relevant for the **Managed by Equals** KYC model. If you use the **Hybrid** or **Delegated** model, you handle verification yourself and won't receive this webhook.
</Info>

<Warning>
  This webhook replaces the existing `KycUpdate` event. If you are currently integrated with `KycUpdate`, you will be notified when to migrate to `IdentityVerificationRequest`.
</Warning>

***

## Step 2: Additional information

If Equals needs additional information to complete the review, you'll receive one of these webhooks depending on the account type:

* **`KycInformationRequested`** - for personal account applications
* **`KybInformationRequested`** - for business account applications

Each webhook carries an `id` that identifies the information request itself, and a `requiredInformation` array describing exactly what is needed. Each item in the array specifies a `code` (the type of information requested, for example `PROOF_OF_ADDRESS` or `PROOF_OF_FUNDS`) and an `expectedResponseType` (`file`, `text`, `boolean`, or `date`) so your integration knows how to collect and validate the response.

**Key fields (`KycInformationRequested`):**

| Field                   | Description                                                                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | The ID of the information request. Use this when responding via the API.                                                                       |
| `applicationId`         | Links this request back to the original onboarding submission.                                                                                 |
| `name`                  | The full name of the applicant.                                                                                                                |
| `email`                 | The email address of the applicant.                                                                                                            |
| `requiredInformation`   | An array of items the applicant needs to provide. Each item has a `code` and an `expectedResponseType` (`file`, `text`, `boolean`, or `date`). |
| `additionalInformation` | Free-text context from the onboarding agent providing additional instructions. May be `null`.                                                  |

**Key fields (`KybInformationRequested`):**

| Field                   | Description                                                                                                                                                     |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                    | The ID of the information request. Use this when responding via the API.                                                                                        |
| `applicationId`         | Links this request back to the original onboarding submission.                                                                                                  |
| `registeredName`        | The registered name of the business.                                                                                                                            |
| `tradingNames`          | An array of the business's trading names.                                                                                                                       |
| `applicant`             | The person who submitted the application, including `id`, `firstName`, `lastName`, and `emailAddress`.                                                          |
| `requiredInformation`   | An array of items requested at the business level. Each item has a `code` and an `expectedResponseType` (`file`, `text`, `boolean`, or `date`).                 |
| `associatedPeople`      | An array of directors, beneficial owners, or other individuals who need to provide information. Each entry has an `id` and its own `requiredInformation` array. |
| `additionalInformation` | Free-text context from the onboarding agent providing additional instructions. May be `null`.                                                                   |

<Info>
  This step may not occur if all submitted information is sufficient. Not every application triggers an information request.
</Info>

<Tip>
  While an information request is outstanding, the application response also exposes an `isActionRequired: true` flag, so you can reconcile state via the API as well as via the webhook. To list every application currently stalled on a customer response, call [`GET /v2/applications?isActionRequired=true`](/api-reference/onboarding/list-onboarding-applications). This flag covers RFIs only — it is not set during GuidedID identity verification.
</Tip>

### Responding to the request

Submit a response for each item in the `requiredInformation` array using the information request ID from the webhook payload.

* For items at the business or personal level, call [Respond to an information request item](/api-reference/onboarding/respond-to-an-information-request-item):

  `POST /v2/applications/{applicationId}/information-requests/{informationRequestId}/respond`

* For items under an entry in `associatedPeople`, call [Respond to an associated person information request item](/api-reference/onboarding/respond-to-an-associated-person-information-request-item):

  `POST /v2/applications/{applicationId}/information-requests/{informationRequestId}/associated-people/{associatedPersonId}/respond`

Each request takes the `code` from the `requiredInformation` item you're responding to and a `response` value formatted according to the item's `expectedResponseType`. The response is validated server-side.

For full payload structures, see [`KycInformationRequested` event details](/pages/webhooks/about-event-types#kycinformationrequested) and [`KybInformationRequested` event details](/pages/webhooks/about-event-types#kybinformationrequested).

***

## Step 3: Application outcome

Once the review is complete, you'll receive an `ApplicationStatusUpdated` webhook with the final outcome.

**Key fields:**

| Field           | Description                                                     |
| --------------- | --------------------------------------------------------------- |
| `decision`      | The outcome of the application: `approved` or `declined`        |
| `applicationId` | Links this decision back to your original onboarding submission |
| `name`          | The full name of the applicant                                  |

<Warning>
  If the application is **declined**, you will not receive an `AccountActivated` event. Contact your account manager if you need more information about a declined application.
</Warning>

For the full payload structure, see [`ApplicationStatusUpdated` event details](/pages/webhooks/about-event-types#applicationstatusupdated).

***

## Step 4: Account activation

If the application was approved, you'll receive an `AccountActivated` webhook confirming the account is open and ready to trade. This is the final event in the onboarding process.

This event contains the full account details, including settlement information with bank details across multiple currencies.

**Key fields:**

| Field               | Description                                                                                                 |
| ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `id`                | The account ID                                                                                              |
| `status`            | The account status: `active`                                                                                |
| `type`              | The account type: `Business` or `Personal`                                                                  |
| `settlementDetails` | An array of bank details per currency, including `sortCode`, `accountNumber`, `iban`, `bic`, and `bankName` |
| `details`           | Account details including `name`, `countryOfRegistration`, and `timezone`                                   |

For the full payload structure, see [`AccountActivated` event details](/pages/webhooks/about-event-types#accountactivated).

***

## Next steps

* [Set up webhooks](/pages/webhooks/how-it-works) - If you haven't already configured your webhook subscriptions
* [About webhook event types](/pages/webhooks/about-event-types) - Full payload reference for all event types
* [List all accounts](/pages/accounts/tutorial/step3) - Continue with the accounts tutorial