Skip to main content

KYC Verification via Redirect Integration

This documentation describes a redirect-based integration for the KYC (Know Your Customer) process. Instead of embedding an IFrame, your application opens the hosted KYC flow in a new browser tab. After the user completes verification and clicks Finish, the hosted app redirects back to the callback URL configured in your developer dashboard, appending both validationId and sessionId query parameters.

1. Initialize a KYC Session​

Start a KYC session by calling the API. Each session links to your dashboard integration, which defines the callback URL and other settings.

POST https://authenticalls.com/kyc/client/api/sessions/start
Content-Type: application/json
Authorization: Bearer <YOUR_API_KEY>

Request Payload (JSON): Include customer data as per the Customer Data Payload documentation.

Successful Response (JSON):

{
  "sessionId": "<SESSION_ID>"
}

2. Launch the KYC Flow in a New Tab​

With the returned sessionId, build the KYC URL. Your integration already knows the callback URL, so only the session identifier is needed.

// After obtaining sessionId:
const kycUrl =
  `https://authenticalls.com/kyc/client/app/intro` + `?sessionId=${sessionId}`;

// Open in new tab:
window.open(kycUrl, "_blank");

Query Parameters​

  • sessionId (required): The unique identifier returned by the API.

3. Handle KYC Completion via Preconfigured Callback​

When the user finishes the KYC flow, the hosted KYC app shows a Finish button. Clicking it redirects the browser to your preconfigured callback URL, adding two query parameters:

{callback_url}?validation={validationId}&session={sessionId}
  • validationId: Unique ID for the completed KYC validation.
  • sessionId: The original session identifier.

Use validationId to fetch detailed verification results:

GET https://authenticalls.com/kyc/client/api/validations/{validationId}/verdict
Authorization: Bearer <YOUR_API_KEY>

Refer to the Get KYC Verdict documentation for response structure.

4. Basic Integration Flow​

By sending only the sessionId when launching the flow, you leverage dashboard-configured callback routing. After redirect, use the validationId to retrieve full KYC details, keeping client logic minimal and secure.

5. Optional: Webhook Notification​

In addition to the callback redirect, you can opt in to receive server-side webhooks when validation completes. Configure your webhook URL in the developer dashboard.

Webhook Request:

POST {webhook_url}
Content-Type: application/json

Payload:

{
  "validation": {
    "id": "<VALIDATION_ID>", // validation id
    "status": "approved", // enum: ValidationStatus
    "integration": {
      "trustedOrigin": "https://yourapp.com",
      "redirectUrl": "https://yourapp.com/kyc/callback",
      "type": "web", // enum: IntegrationType
      "playground": false,
      "integrationName": "DefaultIntegration"
    },
    "document_images": [
      // URLs to ID document images
      "https://cdn.authenticalls.com/front.jpg",
      "https://cdn.authenticalls.com/back.jpg"
    ],
    "selfie_image": "https://cdn.authenticalls.com/selfies/user123.jpg",
    "customerData": {
      // BaseCustomerData
      "firstName": "John",
      "lastName": "Doe"
      // ...other customer data fields as configured
    },
    "sessionId": "<SESSION_ID>" // the associated session id
  }
}

Your backend can immediately process this webhook to update user status or trigger downstream workflows.

Integration Flow with Webhook​