Skip to main content

Complete ID check Onboarding Guide

This guide is written for developers who are integrating ID check into their service for the first time. It walks through the real concerns you’ll face during integration, step by step, introducing the technologies ARGOS provides at each stage.
Prerequisites

Core Principle of ID check Integration

There is one critical thing to understand first when integrating ID check into your system.
ID check is a Liveform-based service.The entire identity verification process (capturing ID documents with camera, taking selfies, AI verification) takes place on the Liveform hosted by ARGOS. Customers cannot build or replace this UI themselves.There is only one thing you need to do: Send your users to the Liveform URL.
Role of the API: The ID check API serves as a pipeline for the secure transfer of information to and from the ARGOS system. Its main purposes are:

Table of Contents

Part 1: Foundation

Account setup, core concepts

Part 2: Integration

Liveform connection, receiving results, data utilization

Part 3: Production

Security hardening, testing, going live

Part 1: Foundation

What is ARGOS ID check?

ARGOS ID check is an AI-powered identity verification platform. When users capture their ID documents and take selfies, the AI analyzes document authenticity and delivers verification results.

Document Verification

Verify passports, driver’s licenses, national IDs, residence permits, and other identity documents issued by a wide range of countries.

AI Fraud Detection

Automatically detect forgery, photo substitution, and document tampering with AI.

Data Extraction

Automatically extract name, date of birth, nationality, and other information from ID documents.

KYC/AML Compliance

Customizable verification rules and audit trail capabilities.

Account Setup and Essential Information

1

Create Your Account

Sign up at idcheck.argosidentity.com, verify your email, and log in to the dashboard.
2

Confirm Essential Information

Confirm the following three items from the dashboard. Each item can be found under the Project Management menu in the new dashboard.1. Project ID (PID) and Liveform URLNavigate to Project Management → Project Settings → Project Info to confirm.
  • Project ID (PID) — Unique project identifier
  • Liveform URL — The identity verification page URL to provide to users (under the Project Pipeline section)
Project Info — PID and Liveform URL

Confirm PID and Liveform URL on the Project Info page

2. API KeyNavigate to Project Management → Project Settings → Integration Info to confirm.
  • API Key — Used for API request authentication (never expose externally)
Integration Info — API Key

Confirm API Key on the Integration Info page

Security Note: Treat your API key like a password. Never expose it in client-side code (frontend) or commit it to git. Always store it in server-side environment variables.

Core Concepts

A Submission represents a single identity verification attempt. When a user captures and submits their ID document on the Liveform, a Submission is created.Key Properties:
  • Submission ID — Unique identifier (e.g., sub_abc123)
  • KYC Statusapproved, rejected, pending (awaiting manual review), incomplete (not submitted / unfinished)
  • Extracted Data — Name, date of birth, nationality, etc.
  • Images — ID document photos and selfies
  • Metadata — Timestamps, IP address, userid/email passed by the customer, etc.
Submission Status Flow:
Liveform is the identity verification page hosted by ARGOS. Customers simply need to provide this URL to their users.
  • Desktop: Displays a QR code for mobile scanning
  • Mobile: Proceeds directly to the camera interface
Base URL Structure:
You can customize user information, country restrictions, security options, and more by adding query string parameters.
Webhooks send real-time HTTP POST requests to your server when verification events occur. This is the most recommended method for receiving verification results in production.Key Events:
  • approved — Verification approved
  • rejected — Verification rejected
  • submit — Submitted with pending status
  • updated — Data updated
  • delete — Submission deleted
  • created — Submission created
  • retry — User retry
  • token_expired — Token expired
  • injection — Data injected via API
  • aml — AML check completed
  • aml_monitor — AML ongoing monitoring result
Register your webhook URL in Project Management → Project Settings → Integration Info.
Using a Token makes Liveform URLs one-time use (Private Mode).Use Cases:
  • Prevent the same URL from being shared with multiple people
  • Provide verification links valid only for specific users
  • Use in security-critical services (finance, healthcare, etc.)
How It Works:
  • Generate a unique tokenId on your server and register it with ARGOS
  • Add the token parameter to the Liveform URL and deliver it to the user
  • Expires 3 minutes after first use or when the submission reaches a decision state
Return URL is the URL where users are redirected after completing verification and clicking “OK” or after 5 seconds.Set it in the dashboard, and KYC status (kycStatus), email, userid, custom fields, etc. are passed as query parameters.Example:
Return URL is for user experience (UX) flow. Use webhooks as the official channel for receiving verification results.
Query strings customize Liveform behavior:
  • email, userid, cf1~cf3 — Pre-fill user information
  • blacklistCountries=false, ageLimit=false — Temporarily override policies
Security-sensitive parameters must be encrypted:
  • allowedCountries — Restrict allowed countries
  • allowedIdTypes — Restrict allowed document types
  • selectedIssuingCountry, selectedIdType — Skip selection screens
  • token — Private mode token
Encryption Modules:
  • AES-256-ECB — Fast and simple block encryption
  • AES-256-GCM — Enhanced encryption with authentication and integrity features
Encryption Keys:
  • API Key — The default API key assigned to the project
  • Custom secretKey — A dedicated key issued separately from the dashboard (shown only once after issuance; must be reissued if lost)
Use the dashboard’s Query String Encryption/Decryption Tool (Project Management → Project Settings → Project Info) to generate and test encrypted URLs directly without writing code.Learn more: Query String & Token Guide | Encryption Guide

Part 2: Integration

Solve the real concerns developers face, step by step.

Q1. “How do I have users verify their identity from my app?”

Answer: Send users to the Liveform URL. Copy the Liveform URL from the dashboard and deliver it to users via button links, redirects, email links, or any other method.
1

Get Your Liveform URL

Copy the Liveform URL from Project Management → Project Settings → Project Info (Project Pipeline section) in the dashboard:
2

Deliver to Users from Your App

Web App — Link Button:
Mobile App — Open External Browser:
Backend Redirect:
3

Test the Basic Flow

Open the URL directly in a browser to test the basic verification flow.
Liveform Interface from pc
Liveform Interface from mobile
  • Desktop: QR code is displayed; scan with mobile to continue
  • Mobile: Proceeds directly to camera interface

Q2. “Can I pass my service’s user information in advance?”

Answer: Add query string parameters to the URL. If users have already signed up, pre-filling their email, user ID, etc. means they won’t need to re-enter this on the Liveform. These values are also saved with the Submission data and can be used later when querying via webhooks or the GET Submission API. Key Parameters: Example URL:
By putting your internal system’s user ID in userid, you can later look up that user’s verification results directly via webhooks or the GET Submission API.

Q3. “I’m concerned about the URL being shared with multiple people”

Answer: Register a Token to use Private Mode (one-time URL). Adding a Token to the Liveform URL makes it one-time use. After first use, once 3 minutes pass or verification completes, it can no longer be used.
1

Generate a Unique tokenId on Your Server and Register with ARGOS

Response:
The Token registration API must only be called from the server side. Since it includes the API key, it must never be called directly from the client (frontend).
2

Deliver the Tokenized Liveform URL to the User

3

Handle Token Expiration

Tokens become invalid when:
  • 3 minutes have passed since first use
  • The Submission associated with the Token reaches a decision state (approved/rejected/pending)
When a token expires, generate a new one and deliver it to the user.Token Limitations:
  • Maximum 100,000 tokens per project
  • Maximum 500 tokens per API request
  • Token ID format: 8–64 characters, alphanumeric + -_.
Learn more: POST Token API | Query String & Token Guide

Q4. “I want to allow only specific countries or document types”

Answer: Use encrypted query string parameters. Security-sensitive parameters like allowedCountries and allowedIdTypes must be encrypted and placed in the encrypted parameter. You can choose between AES-256-ECB or AES-256-GCM encryption modules, and use either the project API key or a Custom secretKey issued separately from the dashboard as the encryption key.
Generate Encrypted URLs Directly from the DashboardTo generate and test encrypted Liveform URLs without writing code, use the dashboard’s Query String Encryption/Decryption Tool.Project Management → Project Settings → Project Info → Query String Encryption/Decryption ToolEnter the parameters to encrypt and an encrypted URL is automatically generated. You can also decrypt existing encrypted URLs to verify the included parameters.
Query String Encryption/Decryption Tool

Query String Encryption/Decryption Tool

Encrypting with Code:
Parameters Requiring Encryption:
selectedIdType must always be used together with selectedIssuingCountry. Using it alone will cause an error.
Learn more: Query String & Token Guide

Q5. “I want to redirect users back to my app after verification”

Answer: Set up a Return URL in the dashboard. When users finish verification and click “OK”, they are redirected to the configured URL. KYC results are passed as query parameters.
1

Set Return URL in Dashboard

Enter the Return URL in Project Management → Project Settings → Integration Info:
Return URL Settings

Return URL Settings

2

Handle the Redirect Results

Users are redirected with the following parameters:
Parameters Passed:
  • kycStatusapproved, rejected, pending
  • userid — User ID passed in the Liveform URL
  • email — User email
  • cf1, cf2, cf3 — Custom fields
The kycStatus passed via Return URL is for user experience (UX) screen transitions. For officially recording verification results in your database or reflecting them in internal systems, it is recommended to use webhooks. Return URL parameters can be tampered with.
Learn more: Return URL Guide

Q6. “I want to receive verification results on my server in real time”

Answer: Set up Webhooks. Webhooks send instant HTTP POST requests to your server when verification events occur. This is the most reliable and recommended method for receiving verification results.
1

Create a Webhook Endpoint

Create an HTTPS endpoint on your server to receive POST requests:
Important Webhook Implementation Principles:
  • ARGOS typically delivers webhooks within 5 seconds of the event. Webhooks are one-way notifications and are not automatically retried on delivery failure. To guard against missed events, consider using the GET Submission API as a reconciliation fallback.
  • Return 200 OK as soon as the request is received and run any heavy processing asynchronously.
  • Implement idempotency handling because the same trigger (e.g. updated) can fire again for the same Submission ID.
2

Register Webhook URL in Dashboard

Enter the endpoint URL in the Webhook Settings section under Project Management → Project Settings → Integration Info:
Webhook setup screen

Webhook URL Settings

Webhook URLs must use HTTPS. For local development, use ngrok or webhook.site for testing.
3

Review Webhook Events

All Event Types:Learn more: Webhook Events Detailed Guide

Q7. “I want to integrate verification data with our DB/system”

Answer: Use the GET Submission API to query verification data. While real-time reception via webhooks is possible, use the GET Submission API when you need to directly query specific Submission data at a given point in time.
Query Parameters: Response Example:
Other Data Management and System Integration APIs:
POST /submission/review allows customers to review pending submissions directly via API when the project reviewer is set to ‘Client’. Already approved/rejected submissions cannot be modified.
Learn more: GET Submission API | Review API

Q8. “I want to migrate existing KYC data to ARGOS”

Answer: Use the POST Submission API (Migration). This API is used in the following situations:
  • Data Migration: Transfer KYC-completed data from existing systems to the ARGOS dashboard
  • Special Situations: Directly insert data in exceptional cases where ID Check verification is difficult
  • Development and Testing: Use during development to test various scenarios
Submissions created through this API do not go through ARGOS’s standard verification process (AI verification). The accuracy and validity of submitted data is entirely the customer’s responsibility.Standard identity verification for new users must always be done through the Liveform.
Required Fields: Optional Fields: idType, issuingCountry, nationality, gender, issueDate, expireDate, identityNumber, documentNumber, userid, cf1~cf3, etc. Notes:
  • Only string data is supported. For image data, use the PUT Image API separately.
  • For enhanced security, you can encrypt the request body with AES-256-ECB before sending.
Learn more: POST Submission API

Part 3: Production Deployment

Security Hardening

Complete these security configurations before deploying to production.
API keys must never be exposed in client-side code (frontend) or git.Use Environment Variables (Required):
Backend Proxy Pattern (Recommended):
Make sure to add to .gitignore:
Registering server IPs that call the ARGOS API in the whitelist blocks API access from unauthorized IPs (403).Register your server IPs in Project Management → Project Settings → System Operation → IP Whitelist Management:
IP Whitelist Management

IP Whitelist Management

You must register all server IPs that call the API: production servers, staging servers, CI/CD pipeline IPs, etc.
You can encrypt sensitive KYC data transmitted via webhooks.Set “Secure Data Transfer” to ON in Project Management → Security Settings → Data Protection.
Secure Data Transfer settings

Secure Data Transfer Settings

When enabled, webhook payloads are delivered encrypted in the following format:
Decryption Method (AES-256-CBC):
Encryption Method Differences:
  • Webhook decryption: AES-256-CBC
  • API requests/responses: AES-256-ECB
  • Query strings: AES-256-ECB or AES-256-GCM
Do not confuse the encryption methods for each purpose.
Learn more: Encryption Guide

Test Checklist

Verify the following items before deploying to production.
1

Liveform Flow Testing

  • Basic Liveform URL loads properly on desktop/mobile
  • QR code scans on mobile and flow proceeds
  • Camera permission request works correctly
  • Document and selfie capture followed by submission completes
  • User information is pre-filled with email, userid parameters
  • Encrypted parameters (allowedCountries, etc.) work correctly
  • Private mode URL with Token works properly
  • Appropriate error screen is displayed when accessing an expired Token
  • Redirected to Return URL after verification completion
  • kycStatus, userid, email parameters are passed correctly
  • Parameters are passed via encrypted parameter when encryption option is enabled
2

Webhook Testing

Test Method 1: Using webhook.site
Test Method 2: Using ngrok (local development)
  • Webhook endpoint receives events properly
  • approved, rejected, submit events are processed correctly
  • 200 OK response is returned immediately on webhook receipt
  • Idempotency handling for duplicate webhooks works
  • Encrypted webhooks are decrypted correctly
3

API Testing

  • GET Submission returns correct data
  • Querying by userid, email works
  • Token registration (POST Token) and retrieval (GET Token) work properly
  • Only authorized IPs can access when IP whitelist is enabled
  • 403 response is returned for requests with invalid API keys
4

Security Testing

  • API key is not exposed in client-side code
  • API key is not included in git history
  • Webhook URL uses HTTPS
  • Permissions are not granted based solely on Return URL parameters (verified via webhook)

Production Transition Checklist

1

Final Dashboard Settings Verification

  • Webhook URL is set to production server address (HTTPS)
  • All production server IPs are registered in IP whitelist
  • Secure Data Transfer (webhook encryption) is configured as needed
  • Return URL is set to production app address
  • Project settings (allowed document types, country blacklist, age limits, etc.) match requirements
2

Final Code Verification

  • API key is loaded from environment variables
  • No hard-coded API keys in the code
  • Error handling and logging are implemented in webhook handler
  • Webhook idempotency handling is implemented
  • Frontend does not call ARGOS API directly
3

Monitoring Setup

Key metrics to track in production:
  • Verification starts vs. completions
  • Approved / Rejected / Pending ratios
  • Webhook reception failure rate
  • Token reissuance frequency due to expiration

Next Steps

Once you’ve completed integration, explore advanced features with the documentation below.

Query String & Token Guide

All options for Liveform customization

Webhook Events Reference

Detailed guide for each event’s payload

Encryption Guide

AES-256-ECB, GCM, CBC encryption implementation

API Reference

Full API specifications for GET Submission, Token API, and more

Return URL Guide

Post-verification redirect configuration

Recommended Browsers & Devices

Check Liveform supported environments