Integration Guide

This document explains the steps required to integrate identity verification with our system.

---

Authentication keys

To integrate, you will need two keys:

1. API Key – identifies your application.
2. Signature Key – used to create and verify request signatures.

Keep these credentials safe. The Signature Key must never be exposed in frontend code.

---

Initialize identity verification

To start an onboarding session, call Endpoint 1 using both your API Key and Signature Key.

How signature works

Every request must be signed with an HMAC SHA-256 hash of the request body using your Signature Key.

• The result is sent in the request header X-Signature.
• On our side, we recompute the signature the same way and validate it using hash_equals. Example (PHP):

PHP

<?php

class RequestSigner
{
    public static function sign(Request $request, string $signatureKey): string
    {
        return hash_hmac('sha256', $request->getContent(), $signatureKey);
    }
}

JavaScript

import crypto from "crypto";
class RequestSigner {
  static sign(requestBody, signatureKey) {
    return crypto.createHmac("sha256", signatureKey).update(requestBody).digest("hex");
  }
}

Endpoint 1: Initialize onboarding session

Request

POST https://api.insyko.com/api/v1/onboardings/{onboardingId}/initiate
X-Api-Key: <API Key>
X-Signature: <HMAC signature>
Content-Type: application/json
{
  "user_consent": true
}

json

HTTP/1.1 200 OK
Content-Type: application/json
{
  "type": "success",
  "is_toast": false,
  "message": "Request has been processed successfully.",
  "auth": {
        "user": {
            "id": 1723,
            "applicantId": null,
            "key": null,
            "name": "Default",
            "steps": [
                {
                    "id": 2195,
                    "key": null,
                    "type": {
                        "name": "INSYKO",
                        "value": "insyko",
                        "displayValue": "Identity verification",
                        "color": null,
                        "icon": null,
                        "iconColor": null
                    },
                    "name": "Default",
                    "order": 1,
                    "stepableId": null,
                    ...
                }
            ],
            ...
            "expiresAt": "2025-09-01T15:20:03+00:00",
            "createdAt": "2025-08-25T15:20:03+00:00",
            "updatedAt": "2025-08-25T15:20:03+00:00"
        },
        "token": "fBIHBAfRFJqEBakNYZ4KZ5HCOilqwfiY1K7Cayk4LEJaUVPkKRwP3A569TV9V3Dx"
    }
}

TIP

• auth.user.applicant_id is the unique ID of the applicant created for this onboarding session.
• auth.token is the access token to be used in all subsequent requests for this session.
• auth.steps contains the list of steps to be completed in this onboarding session.
• auth.user.id is the unique ID of this onboarding session.
• auth.user.expiresAt indicates when this onboarding session will expire.

Redirect URL to onboarding session

To redirect a user into the onboarding session, build the URL with the following structure:

https://v2.onboarding.insyko.com/onboarding-info
  ?token={token}
  &onboardingStepId={onboardingStepId}
  &onboardingId={onboardingId}
  &lang={lang}
  &apiKey={apiKey}

Parameter	Description
token	The token returned in the response from Endpoint 1 (auth.token).
onboardingStepId	The step ID to start from (first step in auth.steps).
onboardingId	The onboarding session ID (from auth.user.id).
lang	Language code (e.g. en = English, sk = Slovak, cs = Czech).
apiKey	Your API Key.
autoClose	Boolean field, if set to true the onboarding window will close automatically after the user completes the process. Default is false.

autoClose = Boolean field, if set to true the onboarding window will close automatically after the user completes the process. Default is false.

Example

https://v2.onboarding.insyko.com/onboarding-info?token=eyJhbGciOiJI...&onboardingStepId=123&onboardingId=456&lang=en&apiKey=abcd1234&autoClose=true

{
  "auth": {
    "token": "<span style='color:#22c55e'>fBIHBAfRFJqE...</span>"
  }
}

After successful onboarding

After the user completes the onboarding session, you can check their verification status by calling Endpoint 2.

Endpoint 2: Get applicant status

Request

GET https://api.insyko.com/api/v1/onboardings/{onboardingID}/
X-Api-Key: <API Key>
X-Signature: <HMAC signature>

json

HTTP/1.1 200 OK
Content-Type: application/json
{
  "type": "success",
  "is_toast": false,
  "message": "Request has been processed successfully.",
  "data": {
        "id": 94,
        "name": "John",
        "surname": "Doe",
        "nationality": "SVK",
        "dateOfBirth": "2000-01-01",
        "personalNumber": "000101/9999",
        "gender": "M",
        "preferredCurrency": null,
        "type": null,
        ...
  }
}

The data object contains the applicant's details and verification status. You can find photo of the uploaded ID document in the data.identityVerifications array.