Check Verification Status
curl --request GET \
--url http://api.gu1.ai/api/kyc/validations/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/api/kyc/validations/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/api/kyc/validations/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/api/kyc/validations/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations/{id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"status": "<string>"
}Session-based validation
Check Verification Status
Query KYC validation results and verification details — in the gu1 KYC API for identity verification flows, with examples for check status use cases.
GET
/
api
/
kyc
/
validations
/
{id}
Check Verification Status
curl --request GET \
--url http://api.gu1.ai/api/kyc/validations/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/api/kyc/validations/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/api/kyc/validations/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/api/kyc/validations/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations/{id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"status": "<string>"
}Overview
After a customer completes their KYC verification, you can query the results to check the verification status, extracted data, and decision details. This is useful for:- Checking if verification is complete
- Retrieving verified customer information
- Getting verification results and risk assessment
- Auditing verification history
While you can poll this API, we strongly recommend using webhooks to receive real-time notifications when verification completes.
Get Validation by ID
Retrieve a specific validation using its ID:Endpoint
GET https://api.gu1.ai/api/kyc/validations/{id}
Example
const validationId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/validations/${validationId}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const validation = await response.json();
console.log('Status:', validation.status);
console.log('Verified:', validation.status === 'approved');
if (validation.status === 'approved') {
console.log('Verified data:', validation.extractedData);
console.log('Verified fields:', validation.verifiedFields);
}
import requests
validation_id = '550e8400-e29b-41d4-a716-446655440000'
response = requests.get(
f'https://api.gu1.ai/api/kyc/validations/{validation_id}',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
validation = response.json()
print('Status:', validation['status'])
print('Verified:', validation['status'] == 'approved')
if validation['status'] == 'approved':
print('Verified data:', validation['extractedData'])
print('Verified fields:', validation['verifiedFields'])
Get Current Validation for Entity
If you don’t have the validation ID, retrieve the current active validation for a person entity:Endpoint
GET https://api.gu1.ai/api/kyc/entities/{entityId}/current
Example
const entityId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/entities/${entityId}/current`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
if (response.status === 404) {
console.log('No active validation for this entity');
} else {
const validation = await response.json();
console.log('Current validation:', validation.status);
}
import requests
entity_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.gu1.ai/api/kyc/entities/{entity_id}/current',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
if response.status_code == 404:
print('No active validation for this entity')
else:
validation = response.json()
print('Current validation:', validation['status'])
Get Entity KYC Status
Get a summary of an entity’s KYC verification status:Endpoint
GET https://api.gu1.ai/api/kyc/entities/{entityId}/status
Response
{
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"hasKyc": true,
"isVerified": true,
"currentValidation": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "approved",
"verifiedAt": "2025-01-15T11:00:00Z"
},
"lastVerifiedAt": "2025-01-15T11:00:00Z",
"expiresAt": "2026-01-15T11:00:00Z",
"needsReverification": false
}
Example
const entityId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/entities/${entityId}/status`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const status = await response.json();
if (status.isVerified) {
console.log('✅ Customer is verified');
console.log('Verified on:', status.lastVerifiedAt);
if (status.needsReverification) {
console.log('⚠️ Needs reverification');
}
} else {
console.log('❌ Customer not verified');
}
import requests
entity_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.gu1.ai/api/kyc/entities/{entity_id}/status',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
status = response.json()
if status['isVerified']:
print('✅ Customer is verified')
print('Verified on:', status['lastVerifiedAt'])
if status['needsReverification']:
print('⚠️ Needs reverification')
else:
print('❌ Customer not verified')
Understanding Validation Results
Status Values
string
Current validation status:
pending- Validation created, waiting for customer to startin_progress- Customer is actively completing verification (filling out form)in_review- Verification completed, requires manual review from compliance teamapproved- Verification successful, identity confirmedrejected- Verification failed, identity not confirmedexpired- Verification session expired (typically after 7 days)abandoned- Customer started but didn’t complete verificationcancelled- Validation manually cancelled
Decision object (decision)
When status is approved or rejected, the decision field contains detailed provider results. When a validation reaches a terminal or in-review state with provider results, decision contains the full verification outcome from the KYC flow. Gu1 always stores and returns both shapes for each feature: a singular object (legacy) and a one-element array (current). You can read either id_verification or id_verifications[0]; they are kept in sync. The same applies to liveness / liveness_checks, face_match / face_matches, aml_screening / aml_screenings, and ip_analysis / ip_analyses.
Media fields (front_image, reference_image, images.*, etc.) are Gu1 storage keys (kyc/...) after ingest. Fetch them via the validation media API. Older rows may still contain short-lived HTTPS URLs until synced.
Approved example (complete):
{
"status": "Approved",
"workflow_type": "standard",
"session_id": "7c0fa22d-0cfa-4a78-8090-7c842397e788",
"session_number": 921,
"features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS"],
"images": {
"documentFront": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"documentBack": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-back.jpg",
"selfie": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg"
},
"id_verification": {
"status": "Approved",
"node_id": "feature_ocr",
"document_type": "Passport",
"document_number": "AB123456",
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"date_of_birth": "1990-05-20",
"nationality": "US",
"gender": "M",
"age": 35,
"issuing_state": "US",
"expiration_date": "2030-05-20",
"date_of_issue": "2020-05-20",
"front_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"back_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-back.jpg",
"portrait_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": [],
"matches": []
},
"id_verifications": [
{
"status": "Approved",
"node_id": "feature_ocr",
"document_type": "Passport",
"document_number": "AB123456",
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"date_of_birth": "1990-05-20",
"nationality": "US",
"gender": "M",
"age": 35,
"issuing_state": "US",
"expiration_date": "2030-05-20",
"date_of_issue": "2020-05-20",
"front_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"back_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-back.jpg",
"portrait_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": [],
"matches": []
}
],
"liveness": {
"status": "Approved",
"node_id": "feature_liveness",
"score": 98,
"method": "PASSIVE",
"reference_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-reference.jpg",
"video_url": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-video.webm",
"face_quality": 92.5,
"warnings": [],
"matches": []
},
"liveness_checks": [
{
"status": "Approved",
"node_id": "feature_liveness",
"score": 98,
"method": "PASSIVE",
"reference_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-reference.jpg",
"video_url": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-video.webm",
"face_quality": 92.5,
"warnings": [],
"matches": []
}
],
"face_match": {
"status": "Approved",
"node_id": "feature_face_match",
"score": 95,
"source_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"target_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": []
},
"face_matches": [
{
"status": "Approved",
"node_id": "feature_face_match",
"score": 95,
"source_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"target_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": []
}
],
"aml_screening": {
"status": "Approved",
"node_id": "feature_aml",
"warnings": []
},
"aml_screenings": [
{
"status": "Approved",
"node_id": "feature_aml",
"warnings": []
}
],
"ip_analysis": {
"status": "Approved",
"node_id": "feature_ip_analysis",
"ip_address": "203.0.113.10",
"country": "US",
"region": "New York",
"city": "New York",
"is_vpn": false,
"is_proxy": false,
"warnings": []
},
"ip_analyses": [
{
"status": "Approved",
"node_id": "feature_ip_analysis",
"ip_address": "203.0.113.10",
"country": "US",
"region": "New York",
"city": "New York",
"is_vpn": false,
"is_proxy": false,
"warnings": []
}
]
}
{
"status": "Declined",
"workflow_type": "standard",
"session_id": "7c0fa22d-0cfa-4a78-8090-7c842397e788",
"session_number": 921,
"features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH"],
"images": {
"documentFront": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"selfie": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg"
},
"id_verification": {
"status": "Declined",
"node_id": "feature_ocr",
"document_type": "Passport",
"document_number": "AB123456",
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"front_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"portrait_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": [
{
"risk": "DOCUMENT_AUTHENTICITY_FAILED",
"feature": "ID_VERIFICATION",
"short_description": "Document authenticity could not be verified",
"long_description": "The document failed authenticity checks.",
"log_type": "error"
}
],
"matches": []
},
"id_verifications": [
{
"status": "Declined",
"node_id": "feature_ocr",
"document_type": "Passport",
"document_number": "AB123456",
"first_name": "John",
"last_name": "Doe",
"full_name": "John Doe",
"front_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"portrait_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": [
{
"risk": "DOCUMENT_AUTHENTICITY_FAILED",
"feature": "ID_VERIFICATION",
"short_description": "Document authenticity could not be verified",
"long_description": "The document failed authenticity checks.",
"log_type": "error"
}
],
"matches": []
}
],
"liveness": {
"status": "Declined",
"node_id": "feature_liveness",
"score": 42,
"method": "PASSIVE",
"reference_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-reference.jpg",
"warnings": [
{
"risk": "LIVENESS_FAILED",
"feature": "LIVENESS",
"short_description": "Liveness detection failed",
"long_description": "The liveness check did not pass the required threshold.",
"log_type": "error"
}
],
"matches": []
},
"liveness_checks": [
{
"status": "Declined",
"node_id": "feature_liveness",
"score": 42,
"method": "PASSIVE",
"reference_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/liveness-reference.jpg",
"warnings": [
{
"risk": "LIVENESS_FAILED",
"feature": "LIVENESS",
"short_description": "Liveness detection failed",
"long_description": "The liveness check did not pass the required threshold.",
"log_type": "error"
}
],
"matches": []
}
],
"face_match": {
"status": "Declined",
"node_id": "feature_face_match",
"score": 38,
"source_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"target_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": [
{
"risk": "FACE_MATCH_LOW_CONFIDENCE",
"feature": "FACE_MATCH",
"short_description": "Face match confidence below threshold",
"long_description": "The selfie did not match the document portrait with sufficient confidence.",
"log_type": "error"
}
]
},
"face_matches": [
{
"status": "Declined",
"node_id": "feature_face_match",
"score": 38,
"source_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/document-front.jpg",
"target_image": "kyc/global_gueno_validation_kyc/org-uuid/entity-uuid/validation-uuid/selfie.jpg",
"warnings": [
{
"risk": "FACE_MATCH_LOW_CONFIDENCE",
"feature": "FACE_MATCH",
"short_description": "Face match confidence below threshold",
"long_description": "The selfie did not match the document portrait with sufficient confidence.",
"log_type": "error"
}
]
}
]
}
Verification results
Each feature block indecision includes a status (Approved, Declined, In Review, etc.), optional score, warnings, and media references:
| Feature key | Array alias | Typical fields |
|---|---|---|
id_verification | id_verifications[0] | document_type, document_number, front_image, back_image, portrait_image, warnings, matches |
liveness | liveness_checks[0] | score, method, reference_image, video_url, warnings, matches |
face_match | face_matches[0] | score, source_image, target_image, warnings |
aml_screening | aml_screenings[0] | status, warnings |
ip_analysis | ip_analyses[0] | ip_address, country, is_vpn, warnings |
extractedData, verifiedFields, and top-level warnings (risk codes) for easier integration.
Extracted Data
UseextractedData to update customer records with verified information:
const validation = await getValidation(validationId);
if (validation.status === 'approved' && validation.extractedData) {
// Update customer record with verified data
await updateCustomer(customerId, {
firstName: validation.extractedData.firstName,
lastName: validation.extractedData.lastName,
dateOfBirth: validation.extractedData.dateOfBirth,
nationality: validation.extractedData.nationality,
documentType: validation.extractedData.documentType,
documentNumber: validation.extractedData.documentNumber,
isVerified: true,
verifiedAt: validation.verifiedAt
});
}
List All Validations for Entity
Get the complete verification history for an entity:Endpoint
GET https://api.gu1.ai/api/kyc/entities/{entityId}/validations
Response
{
"validations": [
{
"id": "validation_1",
"status": "approved",
"isCurrent": true,
"createdAt": "2025-01-15T10:30:00Z",
"verifiedAt": "2025-01-15T11:00:00Z"
},
{
"id": "validation_2",
"status": "abandoned",
"isCurrent": false,
"createdAt": "2025-01-10T09:00:00Z"
}
],
"total": 2,
"page": 1,
"limit": 100
}
Sync Validation Status
If you suspect the validation status is out of sync with the identity provider, trigger a manual sync:Endpoint
POST https://api.gu1.ai/api/kyc/validations/{id}/sync
Example
const validationId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/validations/${validationId}/sync`,
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({ force: true })
}
);
const updatedValidation = await response.json();
console.log('Updated status:', updatedValidation.status);
import requests
validation_id = '550e8400-e29b-41d4-a716-446655440000'
response = requests.post(
f'https://api.gu1.ai/api/kyc/validations/{validation_id}/sync',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={'force': True}
)
updated_validation = response.json()
print('Updated status:', updated_validation['status'])
Common Integration Patterns
Pattern 1: Check Before Allowing Action
async function requireVerification(entityId) {
const status = await fetch(
`https://api.gu1.ai/api/kyc/entities/${entityId}/status`,
{
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
).then(r => r.json());
if (!status.isVerified) {
throw new Error('Customer must complete identity verification');
}
if (status.needsReverification) {
throw new Error('Customer identity verification expired. Please reverify.');
}
return true;
}
Pattern 2: Conditional Features Based on Verification
async function getCustomerFeatures(entityId) {
const status = await getKycStatus(entityId);
return {
basicFeatures: true,
advancedFeatures: status.isVerified,
highLimitTransactions: status.isVerified && !status.needsReverification,
internationalTransfers: status.isVerified && hasAmlClearance(status)
};
}
Pattern 3: Periodic Re-verification Check
async function checkReverificationNeeded() {
const stats = await fetch(
'https://api.gu1.ai/api/kyc/stats',
{
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
).then(r => r.json());
// Find entities needing reverification
const validations = await fetch(
'https://api.gu1.ai/api/kyc/validations?status=approved',
{
headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
}
).then(r => r.json());
for (const validation of validations.validations) {
const status = await getEntityKycStatus(validation.entityId);
if (status.needsReverification) {
await notifyCustomerReverification(validation.entityId);
}
}
}
// Run daily
setInterval(checkReverificationNeeded, 24 * 60 * 60 * 1000);
Best Practices
Use Webhooks, Not Polling
Use Webhooks, Not Polling
Instead of repeatedly checking validation status, use webhooks to receive real-time notifications. This is more efficient and provides better user experience.
Cache Verification Status
Cache Verification Status
Store the verification status in your database and update it via webhooks. Don’t query the API on every request.
// Good: Cache in your database
const customer = await db.getCustomer(customerId);
if (customer.isVerified) {
// Allow action
}
// Bad: Query API every time
const status = await api.getKycStatus(entityId);
if (status.isVerified) {
// Allow action
}
Handle Expired Verifications
Handle Expired Verifications
Verifications may expire after a certain period (typically 1 year). Check
needsReverification and prompt customers to reverify when necessary.Store Validation IDs
Store Validation IDs
Always store the validation ID in your database linked to the customer. This allows you to audit verification history and retrieve detailed results later.
Next Steps
Create KYC Validation
Start a new verification session
Webhook Integration
Get real-time notifications
Was this page helpful?