This quickstart covers Identity Verification (KYC) — the most common starting point. For other products, jump directly to:
Prerequisites
Before you begin, you need:
Keep your API Secret confidential. Never expose it in client-side code, public repositories, or frontend applications.
Step 1: Create a Verification Session
Create a verification session by calling the session creation endpoint. Use your API Key and Secret for Basic Auth.
curl -X POST https://ivs.idenfy.com/api/v2/token \
-H "Content-Type: application/json" \
-u "YOUR_API_KEY:YOUR_API_SECRET" \
-d '{
"clientId": "unique-customer-id-123"
}'
import requests
response = requests.post(
"https://ivs.idenfy.com/api/v2/token",
auth=("YOUR_API_KEY", "YOUR_API_SECRET"),
json={
"clientId": "unique-customer-id-123"
}
)
data = response.json()
print(f"Token: {data['authToken']}")
print(f"Redirect URL: {data['redirectUrl']}")
const response = await fetch("https://ivs.idenfy.com/api/v2/token", {
method: "POST",
headers: {
"Content-Type": "application/json",
"Authorization": "Basic " + btoa("YOUR_API_KEY:YOUR_API_SECRET")
},
body: JSON.stringify({
clientId: "unique-customer-id-123"
})
});
const data = await response.json();
console.log(`Token: ${data.authToken}`);
console.log(`Redirect URL: ${data.redirectUrl}`);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://ivs.idenfy.com/api/v2/token");
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_USERPWD, "YOUR_API_KEY:YOUR_API_SECRET");
curl_setopt($ch, CURLOPT_HTTPHEADER, ["Content-Type: application/json"]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
"clientId" => "unique-customer-id-123"
]));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
$data = json_decode($response, true);
echo "Token: " . $data["authToken"];
require "net/http"
require "json"
require "uri"
uri = URI("https://ivs.idenfy.com/api/v2/token")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request.basic_auth("YOUR_API_KEY", "YOUR_API_SECRET")
request.content_type = "application/json"
request.body = { clientId: "unique-customer-id-123" }.to_json
response = http.request(request)
data = JSON.parse(response.body)
puts "Token: #{data['authToken']}"
Response:
{
"authToken": "pgYQX0z2T8msB64gkl...",
"scanRef": "d2714c8a-ec05-11ec-8ea0-0242ac120002",
"clientId": "unique-customer-id-123",
"redirectUrl": "https://ivs.idenfy.com/api/v2/redirect?authToken=pgYQX0z2T8msB64gkl..."
}
Step 2: Redirect Your Customer
Send your customer to the redirectUrl from the response. They will:
- Select their document type and country
- Upload or capture their ID document
- Complete a liveness check (selfie)
Redirect (simplest)
iFrame (embedded)
Mobile SDK
Redirect the user’s browser to the redirectUrl:window.location.href = data.redirectUrl;
Embed the verification flow in your page:<iframe
src="REDIRECT_URL_HERE"
allow="camera; microphone; fullscreen"
allowFullScreen
style="width: 100%; height: 700px; border: none;">
</iframe>
Full iFrame guide → Pass the authToken to the native SDK:// Android
IdenfyController.startIdentification(activity, authToken)
// iOS
IdenfyController.shared.startIdentification(authToken: authToken)
Android SDK → | iOS SDK →
Step 3: Receive Results
Set up a webhook endpoint to receive verification results. Configure your webhook URL in Dashboard → Settings → Webhooks.
{
"final": true,
"status": {
"overall": "APPROVED",
"autoDocument": "DOC_VALIDATED",
"autoFace": "FACE_MATCH",
"manualDocument": "DOC_VALIDATED",
"manualFace": "FACE_MATCH"
},
"scanRef": "d2714c8a-ec05-11ec-8ea0-0242ac120002",
"clientId": "unique-customer-id-123",
"data": {
"docFirstName": "JOHN",
"docLastName": "DOE",
"docNumber": "AB1234567",
"docExpiry": "2028-12-31",
"selectedCountry": "US",
"selectedDocType": "ID_CARD"
}
}
Use the Testing & Sandbox to simulate different verification outcomes before going live.
What’s Next?
Continue with KYC
Session parameters
Customize with country restrictions, document types, liveness, AML checks.
Webhook reference
Full webhook payload with all status codes and data fields.
Select integration method
Compare redirect, iFrame, SDK, and no-code options.
Go live checklist
Everything to verify before switching to production.
Explore Other Products
Business Verification (KYB)
Verify companies, retrieve registry data, screen beneficial owners.
AML Screening
Screen against sanctions, PEPs, and adverse media.
Fraud Prevention
Risk scoring, proxy detection, phone and address verification.
Face Authentication
Re-authenticate returning users with biometric face matching.