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 | 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 |
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.
If Equals Money needs additional information to complete the review, you’ll receive one of these webhooks depending on the account type:
KycInformationRequested - for personal account applicationsKybInformationRequested - 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. |
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.
Responding to the request
Submit a response for each item in the requiredInformation array using the information request ID from the webhook payload.
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 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 |
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.
ApplicationStatusUpdated event details.
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 |
AccountActivated event details.
Next steps
