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
- ARGOS Identity account (Sign up at idcheck.argosidentity.com)
- Dashboard access and API key confirmation
Core Principle of ID check Integration
There is one critical thing to understand first when integrating ID check into your system. 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:| Purpose | Related APIs | Description |
|---|---|---|
| Token Management | POST/GET/DELETE Token | Create and manage one-time URLs in Private mode |
| Data Retrieval & Management | GET/PATCH/DELETE Submission, GET Image | Query, modify, delete verified Submission data, retrieve images |
| System Integration | POST Review, PUT Image | Process pending submissions, add/replace images for workflow integration |
| Migration | POST Submission | Migrate existing KYC data, insert data in special situations, development testing |
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 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.
Account Setup and Essential Information
Create Your Account
Sign up at idcheck.argosidentity.com, verify your email, and log in to the dashboard.
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.
2. API KeyNavigate to Project Management → Project Settings → Integration 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)

- API Key — Used for API request authentication (never expose externally)

Core Concepts
Submission
Submission
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, orpending(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
Liveform
Liveform is the identity verification page hosted by ARGOS. Customers simply need to provide this URL to their users.You can customize user information, country restrictions, security options, and more by adding query string parameters.
- Desktop: Displays a QR code for mobile scanning
- Mobile: Proceeds directly to the camera interface
Webhook
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 approvedrejected— Verification rejectedsubmit— Submitted with pending statusupdated— Data updateddeleted— Submission deletedcreated— Submission createdretry— User retrytoken_expired— Token expiredinjection— Data injected via APIaml— AML check completedaml_monitor— AML ongoing monitoring result
Token — Private Mode
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.)
- Generate a unique tokenId on your server and register it with ARGOS
- Add the
tokenparameter 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
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 and Encryption
Query Strings and Encryption
Query strings customize Liveform behavior:
email,userid,cf1~cf3— Pre-fill user informationblacklistCountries=false,ageLimit=false— Temporarily override policies
allowedCountries— Restrict allowed countriesallowedIdTypes— Restrict allowed document typesselectedIssuingCountry,selectedIdType— Skip selection screenstoken— Private mode token
- AES-256-ECB — Fast and simple block encryption
- AES-256-GCM — Enhanced encryption with authentication and integrity features
- 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)
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.Get Your Liveform URL
Copy the Liveform URL from Project Management → Project Settings → Project Info (Project Pipeline section) in the dashboard:
Deliver to Users from Your App
Web App — Link Button:Mobile App — Open External Browser:Backend Redirect:
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) | campaign_summer |
sid | Submission ID (used for updates) | sub_abc123 |
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.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)
- 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 likeallowedCountries 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.

| 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) |
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.Set Return URL in Dashboard
Enter the Return URL in Project Management → Project Settings → Integration Info:

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.Register Webhook URL in Dashboard
Enter the endpoint URL in the Webhook Settings section under Project Management → Project Settings → Integration Info:

Webhook URLs must use HTTPS. For local development, use ngrok or webhook.site for testing.
Review Webhook Events
All Event Types:
Learn more: Webhook Events Detailed Guide
| Event | Description | Use Case |
|---|---|---|
approved | Verification approved | Update user status, grant service access |
rejected | Verification rejected | Notify user, request resubmission |
submit | Pending status | Admin notification, manual review request |
updated | Data updated | DB synchronization |
deleted | Submission deleted | Clean up related data |
created | Submission created | Track verification starts |
retry | User retry | Monitor retry patterns |
token_expired | Token expired | Issue new token |
injection | Data injected via API (Injection) | API operation logging |
aml | AML check completed | Process compliance results |
aml_monitor | AML ongoing monitoring result | Continuous monitoring processing |
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.| 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) |
| 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
| Field | Description |
|---|---|
admin | Project admin email (must be registered in dashboard) |
email | KYC submitter’s email address |
fullName | Submitter’s full name |
birthDate | Date of birth (YYYY-MM-DD) |
kycStatus | approved or rejected |
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.
Part 3: Production Deployment
Security Hardening
Complete these security configurations before deploying to production.1. Secure API Key Management
1. Secure API Key Management
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:2. IP Whitelist Configuration
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:

3. Enable Webhook Data Encryption
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:Decryption Method (AES-256-CBC):Learn more: Encryption Guide

Test Checklist
Verify the following items before deploying to production.Liveform Flow Testing
Basic Flow
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
Query String Parameters
- User information is pre-filled with
email,useridparameters - 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
Return URL
- Redirected to Return URL after verification completion
-
kycStatus,userid,emailparameters are passed correctly - Parameters are passed via
encryptedparameter when encryption option is enabled
Webhook Testing
Webhook Reception Verification
Webhook Reception Verification
Test Method 1: Using webhook.siteTest Method 2: Using ngrok (local development)
- Webhook endpoint receives events properly
-
approved,rejected,submitevents are processed correctly - 200 OK response is returned within 5 seconds
- Idempotency handling for duplicate webhooks works
- Encrypted webhooks are decrypted correctly
API Testing
- GET Submission returns correct data
- Querying by
userid,emailworks - 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
Production Transition Checklist
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
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
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

