Getting Started - Onboarding

Introduction

This guide helps you integrate with our Client Onboarding API to seamlessly bring new clients on board.

Provided all stages are successful, the client will be onboarded and assigned a Customer Reference ID.

What you’ll need

• An account with Andaria®.

• API Subscription & Certificate (obtained separately).

The Onboarding Process

Walkthrough

1. Start Onboarding

   • Your system makes an HTTP POST request to our ‘/onboarding-services/v1/onboard’ endpoint with the prospective client’s details.

2. Andaria® Validates

   • We check the information you sent.

   • If valid;

     • We generate a unique ‘onboardingID’ for tracking purposes.

       • Use the onboarding ID to get status updates throughout the entire journey via a GET request to ‘/onboarding-services/v1/onboarding/{onboardingID}’.

     • We send you a ‘kycToken’ (in a status update or a webhook notification if subscribed). This will be required in Stage 3, so the customer can perform the KYC process. The kycToken expires after 1 day. If a customer takes longer to start or finalise the KYC process, this token will be expired and invalid. Refresh this token by sending a POST request to ‘onboarding-services/v2/refreshkyctoken[?onboardingId]’.

   • If invalid;

     • We return an error message detailing the issues/s.

3. SumSub® performs KYC

   • For mobile apps;

     • Follow SumSub's mobile SDK documentation (iOS: https://docs.sumsub.com/docs/get-started-ios and Android: https://docs.sumsub.com/docs/get-started-android) specifically the "Initialization" section. Here, you'll initialise the SDK with the provided ‘kycToken’ (as the ‘accessToken’). This is marked in blue on the diagram.

     • This starts the KYC process on the customer’s device.

   • The kycToken expires after 1 day. If a customer takes longer to start or finalise the KYC process, this token will be expired and invalid. Refresh this token by sending a POST request to ‘onboarding-services/v2/refreshkyctoken[?onboardingId]’.

   • The customer will be guided through SumSub's verification steps, including uploading ID documents, and taking a selfie for a liveness check.

   • Once complete, SumSub® sends the verification result back to Andaria®.

4.  Andaria® Finalises

   • If verification is successful;

     • We create the client account and provide a customer reference ID and an account reference ID.

     • This completes the Onboarding process!

   • If verification fails;

     • We stop onboarding and return a 400 error message.

Important Details

Here are some key things to remember:

• Secure Communication: To ensure a secure connection, you’ll need an API subscription and certificate. Refer to separate instructions for obtaining these credentials.

• Customer Actions: In the onboarding diagram, steps highlighted in blue indicate actions required by the Embedded customer.

Onboarding Statuses

The Client Onboarding API uses specific status to communicate the progress of a client’s journey. Here’s a breakdown of the possible statuses:

Retrieving Enum Values (Lookup API)

Several fields within the onboarding payload require enum values. This section details how to retrieve available enums using the lookup API.

Supported Data Types:

1. Get All Enums

   A request to GET ‘/onboarding-services/v1/lookup’ returns a list of all available enum types within the onboarding services. 

   [
       "ContactInfo_residential_address_country",
       "Financials_estimated_global_worth",
       "Financials_net_monthly_income",
       "Financials_source_of_income",
       "Financials_source_of_wealth",
       "IdentityDetails_country_of_birth",
       "IdentityDetails_document_country_of_issue",
       "IdentityDetails_document_type",
       "IdentityDetails_nationality",
       "IdentityDetails_second_nationality",
       "IdentityDetails_third_nationality",
       "Occupation_PEP_REL_title_of_position_held",
       "Occupation_PEP_title_of_position_held",    
       "Occupation_industry", 
       "Occupation_professional_status", 
       "PersonalInfo_gender", 
       "PersonalInfo_marital_status", 
       "Tax_primary_residence", 
       "Tax_secondary_residence", 
       "Tax_third_residence"
   ]

2. Get specific enum values

   To obtain the allowed values, for example, for the ‘IdentityDetails_document_type’ enum, send a request to GET ‘/onboarding-services/v1/lookup/IdentityDetails_document_type’. The response will list the valid document types. 

   [
       {
           "Code": "ID",
           "Description": "ID Card"
       },
       {
           "Code": "PASS",
           "Description": "Passport"
       }
   ]

Webhook Notifications

The Client Onboarding API can send real-time updates about the onboarding process through webhooks. This allows you to automatically react to changes in the onboarding journey within your own system.

To enable webhooks in the Sandbox environment, refer to the Notifications Service - https://developer-sandbox.andaria.com/api-details#api=notification-services.

A sample webhook has been provided below:

{
  "onboardingId": "fd8f9c30-365b-4bf3-aab2-1018020b794f",
  "status": "Validator - In Progress"
}