Developer guide

The Developer Guide provides comprehensive instructions and best practices for integrating with our platform.

Identomat is a service designed to verify human identity and liveness over the Internet. This guide assumes that the integrating organization (hereafter referred to as "the company") operates a web server (referred to as "the company server") at example.com and possesses a company_key. The company_key is a credential used to securely communicate between the company server and the Identomat server (widget.identomat.com).

For enhanced security, companies can optionally implement HMAC authorization. In this case, a secret_key is used to generate and validate HMAC signatures for secure communication.

Procedure

The integration procedure consists of three main steps:

1

Acquiring a session_token.

2

Redirecting the user's browser to widget.identomat.com.

3

Checking for a result.

Acquiring a session token

To acquire a session_token, your backend must send a request to the /begin/ endpoint with the following parameters:

• company_key – Your unique company identifier.

• flags – A JSON object defining global settings for the verification session.

• steps – An array specifying the steps to include in the verification flow. Each step can have its own step-specific flags.

⚠️ The session_token is valid for 15 minutes by default.

Endpoint:

POST https://widget.identomat.com/begin/

Requests can be sent as:

• URL query parameters

• URL-encoded form data

• JSON object in the request body (recommended)

Steps and Flags Structure

• flags : Defines global behavior for the entire session.

• steps : Allows full control of the verification process, enabling you to specify which steps to include (e.g., liveness, identity-document) and configure step-specific flags, such as "allow_face_upload": true for the liveness step.

To ensure compatibility between the old and new methods, both of which need to work together, you should use the 'skip_face' and 'skip_document' flags when using steps.

These flags prevent the 'identity-document' and 'liveness' steps from being duplicated if they already exist in the flow.

Using Configuration or custom steps

You can initiate a session in two ways:

• Via predefined configuration (Recommended):

  • We strongly recommend using predefined configurations via the config_id parameter. Configurations ensure consistency, simplify integration, and reduce the risk of errors. Using configurations also allows us to deprecate legacy custom step handling in the future, helping clients maintain a clean and stable integration.

• Via custom steps and flags: Only use custom steps and flags if you have very specific needs that cannot be satisfied with configurations. Over time, we encourage migrating all custom flows to configurations.

Why configurations matter:

• Simplifies session creation — no need to manually define steps and flags.

• Reduces risk of errors in the verification flow.

• Future-proof — legacy custom step handling will eventually be deprecated.

• Enables Identomat to maintain, improve, and optimize flows efficiently.

• Makes integration easier.

📘 For detailed parameter definitions and examples, refer to the API Reference.

Redirecting to the Identomat Widget

To start a verification session, the company server must redirect the user’s browser to:

https://widget.identomat.com/?session_token={session_token_here}

Replace {session_token_here} with the actual token received from the /begin/ endpoint.

Embedding in an Iframe

Alternatively, the widget can be embedded within an iframe:

<iframe
    src="https://widget.identomat.com/?session_token={session_token_here}"
    allow="camera">
</iframe>

⚠️ The allow="camera" attribute is required to grant camera access.

Checking for a result

Once the verification process is completed, the result can be detected in two ways depending on how the widget was integrated:

• If redirected If you used a redirect approach (not embedded in an iframe), the user will be redirected to the return_url specified in the configuration or session flags. The session_token will be appended as a query parameter:

https://yourapp.com/?session_token=abc123xyz

• If embedded in an iframe, the process completion can be detected using JavaScript:

addEventListener('message', function (e) {
    if (e.origin !== 'https://widget.identomat.com') return;
    if (e.data !== 'DONE') return;
    // Process completed, handle results here
});

✅ Ensure you verify the message origin to avoid security risks.

---

Quick links

Access detailed developer guides for KYC (Know Your Customer) and KYB (Know Your Business) flows. Click a card below to explore configuration, integration steps, and best practices for each verification type.

KYC (Know Your Customer) Learn how to collect and verify individual user data, configure verification steps, and integrate KYC flows.

KYB (Know Your Business)

Learn how to collect and verify company data, beneficiaries, and representatives, with configurable verification steps.