Integrating KYC (Know Your Customer) processes allows you to automate entity verification, collect necessary documentation, and ensure compliance with regulatory requirements. This guide covers the integration of the core KYC flow starting with entity onboarding.

​
Onboarding Entities

To initiate a KYC journey, you must first add the individual or entity to the DAL system as an onboarding entity. This creates the entity record with an Onboarding status and automatically prepares the necessary KYC forms and agreements based on the entity’s classification. Endpoint: View API Reference Once an entity is onboarded, you can use their entityId to manage their KYC process, bank accounts, and addresses. The response also includes the entity’s KYC under data.kyc. Its id is the kycId used in the KYC flow below.
Send identities with the request whenever you have the entity’s ID. It is optional, but a KYC flow that does not include ID verification never collects one, so the entity is promoted to a client with no ID on file. An ID makes screening matches more accurate, and a client without one is flagged as an incomplete profile in the platform until an ID is added through create identity.

​
Core KYC Flow

The core KYC integration involves managing KYC submissions and agreements for your onboarding entities. DAL provides two integration paths depending on how much control you need. Use these apis to handle submissions — you only need the kycId returned when onboarding the entity.

​
1. Fetching Questions

Retrieve the combined set of questions that need to be answered to advance the KYC to its next status. Endpoint: View API Reference

​
2. Submitting Answers

Submit the entity’s answers. The API automatically routes them to the appropriate underlying forms. To finalize the KYC in the same request, pass ?finalize=true. Saving and finalizing either both succeed or both fail: if finalizing fails, for example because a required question is still unanswered, none of the answers are saved and no form is finalized, so the request can be retried once the answers are complete. The response contains the updated KYC, its entity and its scores (newest first). Endpoint: View API Reference

​
3. Finalizing KYC (optional)

Once all answers are submitted, finalize the KYC. This locks all forms (making them non-editable) and transitions the KYC to the next phase in a single call. The response contains the updated KYC, its entity and its scores (newest first). Skip this step if the answers were submitted with ?finalize=true. Endpoint: View API Reference

​
4. (Optional) Requesting upgrading to qualified investor

Enable the qualified upgrade form to be submittable by end client. Endpoint: View API Reference

​
Form-Level Flow (Advanced)

Use this approach if you need direct access to individual forms and their structure, or need fine-grained control over which form is submitted or finalized.

​
1. Retrieving Forms

Each KYC process (e.g., Onboarding, Suitability) consists of one or more forms. Use the IDs to fetch the form structure. Endpoint: View API Reference

​
2. Submitting KYC Data

Submit the collected user data to the corresponding form. Endpoint: View API Reference

​
3. Finalizing a Form

Finalize an individual form to lock it and trigger the KYC transition logic for that form. Endpoint: View API Reference

​
Handling Agreements & Signatures

For processes requiring legal agreements (e.g., Suitability Disclaimers), fetch the pending agreements and submit signatures. Endpoints:

​
Re-issuing a KYC

An entity can be issued a new KYC when it has none yet, when its KYC is complete, or when its KYC ended in a terminal state (KycBlocked, KycRejected, KycDeprecated, KycExpired). A completed KYC moves to KycExpired and is retained for audit; a terminal KYC keeps its status and is likewise retained. Endpoint: View API Reference What the new KYC looks like depends on the flow currently published for the entity’s type and classification:
  • Same flow as before — the new KYC starts at KycPending with the previous answers carried over, so only the responses that changed need resubmitting. Send prefillAnswers: false to start from empty forms instead.
  • A different flow — the new KYC starts at ConsentPolicyPending, or KycPending when the flow has no consent policy. Answers are not carried over, because they belong to a different set of questions, but the entity’s nationality and country of residence are filled in from its verified identity.
The entity is not re-invited and does not re-verify its email. Agreements are signed afresh against the new KYC. The new KYC’s classification is carried forward from the entity’s current one. For an entity that has no classification yet — one that never had a KYC — pass classification in the request body; without it the call fails. For an entity that is already classified, classification may be omitted or must match the current one: a different value returns an error, as the classification cannot be changed through this endpoint. The response returns the new KYC, so it can be acted on without re-listing the entity’s KYCs.
Note: The entity’s latest KYC must be KycComplete, in a terminal state, or absent. Calling this while a KYC is still in progress returns an error.

​
Address Integration

DAL supports both manual and automatic address verification for entities. Endpoints:

​
1. Address Status and Flow

Note: This diagram illustrates the actions and transitions in the address verification process. It does not represent the actual status values. The final statuses (Submitted ,Verified and Failed) are described after the diagram.

​
2. Address Status Descriptions

Submitted The address has been submitted manually and is waiting for verification by an operator or system. Verified The address has been successfully reviewed and validated by an operator or automated verification process, and is approved for use within the system. Archived The address is no longer active or in use and has been retained for record-keeping and audit purposes.

​
Automatic Address Verification

For regions where automatic verification is available, you can use the following flow:
  1. Start Verification: View API Reference (returns an OTP challenge).
  2. Submit Verification: View API Reference (validates the OTP and fetches address data).

​
Banking Integration

Managing entity bank accounts is a critical part of the onboarding process. Endpoints:

​
Webhook Notifications

Stay updated in real-time by listening to KYC-related webhook events.
  • KycSubmissionUpdate: Triggered when a KYC form is submitted.
  • KycStatusUpdate: Triggered when a KYC record is reviewed or status changes.
  • KycAgreementsUpdate: Triggered when an agreement is signed.
For detailed payload schemas, refer to the Webhook Integration guide.

​
KYC Status & Transition Guide

This section provides a step-by-step overview of the KYC process flows for entities, including their statuses, possible transitions and the required actions. It is designed for integrators to understand:
  • Which forms need to be submitted at each stage.
  • What actions trigger transitions (e.g., verifying email, signing agreements, submitting forms).
  • The conditions under which an entity moves from one status to the next.
Following this guide ensures a smooth integration and helps prevent errors during the KYC lifecycle.
Description: This phase covers the initial onboarding of an entity. The entity receives an invitation to start the KYC process, verifies their email, and signs the necessary Consent Policy agreement. Completing this phase allows the entity to proceed to KYC forms.

​
2. KYC Forms & Suitability

Description: In this phase, the entity completes various KYC forms, including Risk Assessment, Suitability, and KYC forms. Depending on the results (e.g., suitability scores, remaining attempts), the entity may need to retake forms, sign disclaimers, or move to risk review.

​
3. Risk Review

Description: Once the entity submits all required forms, the platform performs a risk review. For higher-risk entities, an EDD (Enhanced Due Diligence) form may be required. This phase ensures that risk and compliance checks are passed before proceeding.
Note: The actions in the table refers to actions that can be taken by admin.

​
4. EDD

Description: In this phase, the entity fills out the EDD form. EDD (Enhanced Due Diligence) undergoes a manual review. This step ensures that all risk and compliance checks are successfully completed before moving forward.

​
5. Qualified Investor & AOA

Description: This phase applies to entities classified as Qualified Investors or Retail entities. The entity completes any remaining forms, including the Qualified Investor form if applicable, and signs the Account Opening Agreement (AOA) to finalize the KYC process.

​
6. Upgrade to Qualified Investor

Description: An entity who has completed KYC as a Retail entity can be upgraded to Qualified Investor classification. This sends the entity back through the Qualified Investor form and AOA signing flow.
Note: The action in the table refers to an action that can be taken by admin.
After transitioning to QualifiedPending, the entity follows the same flow as described in Section 5 to submit the Qualified Investor form and sign the AOA.

​
7. Re-issuing a KYC

Description: A completed or terminated KYC can be replaced by a new one so that an entity’s details are re-confirmed, typically on a periodic cadence. A completed KYC transitions to KycExpired and is kept for audit, while a new KYC is created for the entity to work through. A KYC in a terminal state (KycBlocked, KycRejected, KycDeprecated, KycExpired) keeps its status when the new one is issued, and an entity with no KYC yet can be issued its first one the same way.
Note: The action in the table refers to an action that can be taken by admin.
The newly created KYC starts at KycPending, or at ConsentPolicyPending when the entity moves to a different flow that requires a consent policy. From there it follows the same flow as described in Section 2.