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.

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

Make sure you’ve set up your webhooks and subscribed to the relevant event types before submitting an application.

Webhook flow overview

Order	Webhook event	Description	Always received?
1	`IdentityVerificationRequest`	Identity verification link for the applicant	Conditional - Managed by Equals model only
2	`IdentityVerificationStatusUpdated`	Guided ID progress and outcome updates	Conditional - Managed by Equals model only; may fire multiple times
3	`KycInformationRequested` / `KybInformationRequested`	Additional information required	Conditional - only if further information is needed
4	`ApplicationStatusUpdated`	Application approved or declined	Always
5	`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

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.

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

Step 2: Identity verification status

As the applicant works through their identity verification session, you’ll receive an IdentityVerificationStatusUpdated webhook each time the session changes state (to_be_completed → in_progress → completed), with a result once completed. Unlike the other onboarding events, this one may fire multiple times for the same applicant.

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.

For the status lifecycle, the pull alternative, and how to reconcile the two, see Track Guided ID status. For the full payload structure, see IdentityVerificationStatusUpdated event details.

Step 3: 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`.

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

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. This flag covers RFIs only — it is not set during Guided ID.

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: POST /v2/applications/{applicationId}/information-requests/{informationRequestId}/respond
For items under an entry in associatedPeople, call 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 and KybInformationRequested event details.

Step 4: 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

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.

For the full payload structure, see ApplicationStatusUpdated event details.

Step 5: 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.

Next steps

Set up webhooks - If you haven’t already configured your webhook subscriptions
About webhook event types - Full payload reference for all event types
List all accounts - Continue with the accounts tutorial

Group placeholder

Group

Group

Onboarding webhooks

Onboarding webhooks

Webhook flow overview

Step 1: Identity verification

Step 2: Identity verification status

Step 3: Additional information

Responding to the request

Step 4: Application outcome

Step 5: Account activation

Next steps

​Onboarding webhooks

​Webhook flow overview

​Step 1: Identity verification

​Step 2: Identity verification status

​Step 3: Additional information

​Responding to the request

​Step 4: Application outcome

​Step 5: Account activation

​Next steps

Onboarding webhooks

Webhook flow overview

Step 1: Identity verification

Step 2: Identity verification status

Step 3: Additional information

Responding to the request

Step 4: Application outcome

Step 5: Account activation

Next steps