# 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](https://app.kycaid.com/login), navigate to the [Forms](https://app.kycaid.com/forms/list) page, and click **Create new**. Enter a name for the form and click **Save changes**.

To retrieve a `form_id`, go to the [Forms](https://app.kycaid.com/forms/list) 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/forms/form-get-url) API request with the `form_id`, which you can obtain by following the instructions in the [previous section](#getting-an-id-of-a-form).

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/applicants/applicant-create) 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/forms/form-get-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/forms/form-get-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](#getting-a-url-to-a-form)).
- 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](/guides/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`).

All supported languages
All supported languages are listed by **Get languages** request.

### 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.

Set container minimum sizes for an iframe and WKWebView
For the form to display correctly on mobile screen sizes, use the following minimum container dimensions. A minimum height is required for each corresponding width.

- **Width 320 px**: Minimum height 700 px
- **Width 375 px**: Minimum height 715 px
- **Width 425 px**: Minimum height 775 px
- **Width 500 px**: Minimum height 835 px
- **Width 600 px**: Minimum height 950 px
- **Width 700 px**: Minimum height 1060 px
- **Width 767 px**: Minimum height 1135 px


## 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:


```json
{
  "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**](https://docs.kycaid.com/#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**](https://docs.kycaid.com/#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](https://docs.kycaid.com/#retrieve-a-verification) (see `status` property).
- Applicant with [Get an applicant](/api/applicants/applicant-get).
- Document with [Get a document](/api/documents/document-get).


## Understanding verification results

There are three status levels:

1. 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](https://docs.kycaid.com/#retrieve-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


1. 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


1. 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/applicants/applicant-get) 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](/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](#for-users-with-created-applicants) 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.