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.
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 | IdentityVerificationRequested | Identity verification link for the applicant | Conditional - Managed by Equals model only |
| 2 | KycInformationRequest / KybInformationRequest | Additional documentation required | Conditional - only if further documents are 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 IdentityVerificationRequested 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 IdentityVerificationRequested.
If Equals Money needs additional documentation or information to complete the review, you’ll receive one of these webhooks depending on the account type:
KycInformationRequest - for personal account applicationsKybInformationRequest - for business account applications
Key fields (KycInformationRequest):
| Field | Description |
|---|
requiredInformation | The type of document needed: PROOF_OF_ADDRESS, PROOF_OF_IDENTITY, or BANK_STATEMENT |
name | The name of the applicant |
email | The email of the applicant |
additionalInformation | Context about what’s being requested |
applicationId | Links this request back to the original onboarding submission |
| Field | Description |
|---|
registeredName | The registered name of the business |
tradingNames | The trading names of the business |
applicant | The person who submitted the application, including id, emailAddress, and name |
requiredInformation | Documents needed for the business: PROOF_OF_ADDRESS, PROOF_OF_IDENTITY, or BANK_STATEMENT |
associatedPeople | An array of directors, beneficial owners, or other individuals who need to provide documents, each with their own id, name, and requiredInformation list |
additionalInformation | Context about what’s being requested |
applicationId | Links this request back to the original onboarding submission |
This step may not occur if all submitted documents and information are sufficient. Not every application triggers an information request.
KycInformationRequest event details and KybInformationRequest 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 |
|---|
status | 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
