New Omni documentation is now available — policy-driven document verification and API reference. Explore Omni → · Custom Theme for KYC liveform: Learn more →
New Omni documentation is now available — policy-driven document verification and API reference. Explore Omni → · Custom Theme for KYC liveform: Learn more →
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.
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:
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 more from 200+ countries worldwide.
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.
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)
2. API KeyNavigate to Project Management → Project Settings → Integration Info to confirm.
API Key — Used for API request authentication (never expose externally)
API Key: argos_live_abc123xyz...Project ID: pid_abc123Liveform URL: https://form.argosidentity.com?pid=pid_abc123
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.
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 Status — approved, rejected, or pending (awaiting manual review)
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.
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:
https://form.argosidentity.com?pid={project_id}
You can customize user information, country restrictions, security options, and more by adding query string parameters.
Webhook
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
deleted — 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.
Token — Private Mode
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
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:
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:
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:
Parameter
Description
Example
email
User email
user@example.com
userid
Internal user ID
user_12345
cf1, cf2, cf3
Custom metadata (e.g., campaign ID, service identifier)
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
{ "success": true, "message": "All tokens are now in the pool", "summary": { "totalSubmitted": 2, "currentCount": 2 }}
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
const tokenId = "user-session-001";const secureUrl = `https://form.argosidentity.com?pid={your_pid}&token=${tokenId}`;// Deliver to user via email, SMS, etc.sendEmail(userEmail, `Verification link: ${secureUrl}`);
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 + -_.
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.
Encrypting with Code:
const CryptoJS = require('crypto-js');function encryptQueryParams(data, apiKey) { const hashedKey = CryptoJS.SHA256(apiKey); const key = CryptoJS.lib.WordArray.create(hashedKey.words.slice(0, 8), 32); const encrypted = CryptoJS.AES.encrypt( JSON.stringify(data), key, { mode: CryptoJS.mode.ECB } ); return encrypted.ciphertext.toString(CryptoJS.enc.Base64);}// Example 1: Restrict allowed countries and document typesconst config1 = { allowedCountries: "USA,KOR,JPN", // ISO Alpha-3 codes allowedIdTypes: "passport,drivers_license"};// Example 2: Pre-select country and document type (skip selection screens)const config2 = { selectedIssuingCountry: "KOR", selectedIdType: "drivers_license"};const encrypted = encryptQueryParams(config1, YOUR_API_KEY);const liveformUrl = `https://form.argosidentity.com?pid={your_pid}&encrypted=${encodeURIComponent(encrypted)}`;
Parameters Requiring Encryption:
Parameter
Description
allowedCountries
Countries to allow (ISO Alpha-3 codes, comma-separated)
allowedIdTypes
Document types to allow
selectedIssuingCountry
Skip country selection and specify directly
selectedIdType
Skip document type selection and specify directly (must be used with selectedIssuingCountry)
projectionId / projectionName
Apply Projection to exclude specific fields
auxidField
Additional identity verification (e.g., phone number SMS verification)
selectedIdType must always be used together with selectedIssuingCountry. Using it alone will cause an error.
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:
https://yourapp.com/verification-complete
2
Handle the Redirect Results
Users are redirected with the following parameters:
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.
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:
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 single submission by Submission IDcurl -X GET 'https://rest-api.argosidentity.com/v3/submission?submission_id={submission_id}' \ -H 'x-api-key: YOUR_API_KEY'# Query by user IDcurl -X GET 'https://rest-api.argosidentity.com/v3/submission?userid={userid}' \ -H 'x-api-key: YOUR_API_KEY'# Query by emailcurl -X GET 'https://rest-api.argosidentity.com/v3/submission?email={email}' \ -H 'x-api-key: YOUR_API_KEY'# Query full list (pagination)curl -X GET 'https://rest-api.argosidentity.com/v3/submission?count=50' \ -H 'x-api-key: YOUR_API_KEY'
Query Parameters:
Parameter
Description
submission_id
Query a single submission by its unique ID
userid
Query all submissions matching the user ID
email
Query all submissions matching the email
count
Number of results to return (default: 50)
start_date / end_date
Date range filter (YYYY-MM-DD)
request_type
Query only specific data types (kyc, aml, data, others)
Other Data Management and System Integration APIs:
API
Purpose
PATCH /submission
Modify Submission data (kycStatus, fullName, email, etc.)
DELETE /submission
Delete entire Submission (for GDPR data deletion requests, etc.)
DELETE /submission/partial
Delete images only (preserve metadata)
GET /image
Retrieve images stored in a Submission (ID documents, selfies, etc.)
PUT /image
Add or replace images in an existing Submission (Base64 encoded)
POST /submission/review
Approve/reject pending Submissions via API (automate manual review)
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.
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.
// Load in Node.jsrequire('dotenv').config();const apiKey = process.env.ARGOS_API_KEY;
Backend Proxy Pattern (Recommended):
// ❌ Calling ARGOS API directly from frontend — Never do this// fetch('https://rest-api.argosidentity.com/...', { headers: { 'x-api-key': '...' } })// ✅ Frontend calls only your own backend API// Backend server calls ARGOS API and returns resultsapp.post('/api/start-verification', authenticateUser, async (req, res) => { const tokenId = `session-${req.user.id}-${Date.now()}`; // Call ARGOS API only from server side await fetch('https://rest-api.argosidentity.com/v3/submission/tokens', { method: 'POST', headers: { 'x-api-key': process.env.ARGOS_API_KEY, 'Content-Type': 'text/plain' }, body: JSON.stringify({ tokenId: [tokenId] }) }); const liveformUrl = `https://form.argosidentity.com?pid=${process.env.ARGOS_PROJECT_ID}&token=${tokenId}`; res.json({ liveformUrl });});
Make sure to add to .gitignore:
.env.env.local.env.production
2. IP Whitelist Configuration
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:
52.12.34.5652.12.34.57
You must register all server IPs that call the API: production servers, staging servers, CI/CD pipeline IPs, etc.
3. Enable Webhook Data Encryption
You can encrypt sensitive KYC data transmitted via webhooks.Set “Secure Data Transfer” to ON in Project Management → Security Settings → Data Protection.
When enabled, webhook payloads are delivered encrypted in the following format:
Verify the following items before deploying to production.
1
Liveform Flow Testing
Basic Flow
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
Query String Parameters
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
Return URL
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
Webhook Reception Verification
Test Method 1: Using webhook.site
1. Visit https://webhook.site2. Copy the generated unique URL3. Enter it in the dashboard Webhook URL field4. Perform a test verification on Liveform5. Check the payload on webhook.site
Test Method 2: Using ngrok (local development)
# Run local servernode server.js # port 3000# Expose externally in a separate terminalngrok http 3000# Enter the generated HTTPS URL in the dashboard# e.g., https://abc123.ngrok.io/webhooks/idcheck
Webhook endpoint receives events properly
approved, rejected, submit events are processed correctly
200 OK response is returned within 5 seconds
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)