Form integration

A form in Kycaid is a widget designed for seamless integration into your services, supporting KYC (Know Your Customer) and KYB (Know Your Business) processes, such as user identification via document uploads or video interviews.

Getting an ID of a form

An ID of a form (referred to as form_id in our system) is a unique identifier assigned by our system when a form created. This ID is generated in 36-characters UUID format (e.g., 18505b6f056f2143c41b97f4924dca24ea82).

Creating a form

If you have not created a form yet, you have to create one. Log in to the Dashboard, navigate to the Forms page, and click Create new. Enter a name for the form and click Save changes.

To retrieve a form_id, go to the Forms page and click Copy in the Form ID column while hovering over the target form ID:

Highlighted location of the “Copy” icon button

Getting a form URL

From the Dashboard

To obtain the form URL from the Dashboard, click the Link button:

Highlighted location of the “Link” icon button

Then, click the Generate link in the modal window that appears:

Highlighted location of the “Generate link” primary button in the modal window

After the link is generated, you can copy it or open it in the new tab.

Highlighted location of the form URL, together with the “Run” and the “Copy URL” buttons

Using the API

To retrieve a one-time URL for a form using the API, use the Get a form URL API request with the form_id, which you can obtain by following the instructions in the previous section.

One form, multiple URLs

You don’t need to create a new form for every verification. Instead, you can retrieve a unique one-time URL for each user.

For new users

If a user does not have a corresponding applicant in our system, an applicant will be created after the user completes their first form and submits it for verification. Alternatively, you can create an applicant in advance using the Create an applicant object API request.

For users with created applicants

If a user has already submitted a form and you need to provide them with another verification attempt, use the Get a form URL API request with applicant_id of their applicant.

Avoid creating duplicates

If an applicant_id of an applicant was not used, a duplicate applicant will be created, potentially breaking connection between applicants and verifications, and hindering versioning consistency.

Linking applicants to users in your system

When making the Get a form URL API request, you can include a user identifier from your system (e.g. user_id) with the external_applicant_id parameter. This ensures consistency across the whole user verification process and allows you to track your users at each step.

Providing a form to a user

You can provide users with a form using the following methods:

A direct URL to a form (obtained by instructions in the previous section).
Embedding a form in an iframe within a browser.
Displaying the form using a native WebView on iOS or Android devices.

For the iframe native WebView, there are additional settings available, that are listed below.

Custom domain name for a form

See Set up a custom domain name article for instructions on configuring a custom domain name for your forms.

Default form language

By default, our system sets the form language based on the locale of a user browser. However, you can override this using the lang query parameter. In example:

https://forms.kycaid.com/65e5b4121d92424b9e3af5e443cca0d3b024/?lang=en

the default form language is set to English (en).

The following default languages are supported:

az: Azerbaijani
bn: Bengali
de: German
en: English
es: Spanish
es-mx: Spanish (Mexico)
fr: French
he: Hebrew
hi: Hindi
hr: Croatian
kk: Kazakh
nl: Dutch
pl: Polish
pt: Portuguese
ro: Romanian
ru: Russian
tr: Turkish
uk: Ukrainian
uz: Uzbek
yi: Yiddish
zh: Chinese

Settings for an iframe

To ensure proper camera functionality add the following allow attribute to the iframe:

allow="microphone *;camera *;midi *;encrypted-media *;clipboard-read;clipboard-write;"

Our system automatically resizes iframes to adapt to the screen size of the user device.

Settings for iOS WKWebView

Set the allowsInlineMediaPlayback parameter to true to enable proper camera functionality.

Note that the WKWebViewConfiguration should only be used during the first initialisation of the WebView and can’t be changed afterward.

Getting verification status

Using the cross-origin postMessage event

When a user submits a completed form in an iframe, the form triggers a cross-origin postMessage event:

{
  "event": "FORM_COMPLETED",
  "applicant_id": "...",
  "verification_id": "..."
}

This allows your system to handle the form completion event programmatically.

Using the Verification completed callback

Our server provides the results of user verification check by sending the Verification completed callback in JSON format to the URL specified in the form settings:

Highlighted location of the “The URL on which result of verification will come” block

The verification process may take anywhere from 10 seconds to 15 minutes, depending on various factors. It is important to store applicant_id and verification_id from the callback for future operations related to the applicant and verification.

Using the Verification status changed callback

To additionally track when a user completes and submits a form, enable the Send the callback when verification is created option (disabled by default) in the form settings:

Highlighted location of the “Send the callback when verification is created” block

Once enabled, our server will send the Verification status changed callback in JSON format to your server (to the same URL specified in the form settings as for Verification completed callback) when a user submits a form for verification.

Responding to a callback

After sending a callback, our server waits for a 200 HTTP response (with any response body) from your server to confirm successful delivery. If your server does not respond within 10 seconds, another callback is sent 1 minute later, with subsequent retries at these intervals:

5 minutes
10 minutes
30 minutes
1 hour
3 hours
6 hours
12 hours
24 hours.

Controlling restart

To prevent a user from restarting a form after submission, you can disable the button used to open the form upon receiving the Verification status changed callback. Optionally, re-enable it after receiving the Verification completed callback if you want the user to make another verification attempt.

Using API

You can retrieve information about the verification process by making different API requests:

Verification with Get a verification (see status property).
Applicant with Get an applicant.
Document with Get a document.

Understanding verification results

There are three status levels:

The highest level is the verified property of a verification, which defines the overall verification status. This property can be retrieved using the Get a verification API. The verified property may have one of the following values:

null: the applicant is under verification,
true: the applicant has passed verification,
false: the applicant has failed verification

A lower, more specific level is the verifications.{verification_type}.verified property of a verification, which indicates the verification result for a specific verification type. Here, {verification_type} can be one of the following:

profile
document
facial
address
aml
financial
payment_method
tax_id
database_screening
company

verifications.{verification_type}.verified can have one of the following values:

true: a verification has passed for the specific type
false: a verification failed for the specific type

The lowest and most specific level is the decline_reasons property of an applicant, which provides detailed reasons for a failed verification. This property can be retrieved using the Get an applicant API. The decline_reasons property lists specific causes that led to the verification failure, offering deeper insights for troubleshooting and resolution. For a detailed list of possible reasons and their descriptions, refer to the Decline reasons article.

Additional verification attempts

If a user fails the verification process and you want to allow another attempt, generate a new URL for the form (see Getting a form URL section) using the applicant_id from the Verification completed callback. This ensures that our system maintains the connection between data from multiple verifications of the user.