> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Current KYC Validation
> Retrieve the current active KYC validation for an entity — in the gu1 KYC API for identity verification flows, with examples for current validation use cases.
## Overview
This endpoint retrieves the current active KYC validation for a specific entity. The "current" validation is the most recent validation marked with `isCurrent: true`.
**Key features:**
* Returns the active validation for an entity
* Automatically syncs with the KYC provider if images are expired (> 3.5 hours)
* Includes all verification data (documents, biometrics, risk assessment)
* Returns 404 if no current validation exists
## When to Use This
* **Check verification status**: See if an entity has an active KYC validation
* **Display verification data**: Show document and biometric verification results in your UI
* **Validate user identity**: Check if a user has completed KYC before allowing certain actions
* **Compliance checks**: Verify that an entity has valid KYC documentation
## Request
### Endpoint
```
GET https://api.gu1.ai/api/kyc/entities/{entityId}/current
```
### Path Parameters
The ID of the entity to get the current validation for
### Headers
```json theme={null}
{
"Authorization": "Bearer YOUR_API_KEY"
}
```
## Response
### Success Response (200 OK)
Returns the current validation object with all verification data:
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "org_abc123",
"validationSessionId": "session_xyz789",
"status": "approved",
"provider": "Gu1 KYC",
"providerSessionUrl": "https://verify.example.com/session_xyz789",
"isCurrent": true,
"decision": {
"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": []
}
]
},
"extractedData": {
"firstName": "John",
"lastName": "Doe",
"dateOfBirth": "1990-01-15",
"documentNumber": "AB123456",
"documentType": "Passport",
"nationality": "US"
},
"documentsVerified": [
{
"type": "Passport",
"verified": true,
"verifiedAt": "2025-01-27T10:30:00Z"
}
],
"biometricResult": {
"livenessScore": 0.95,
"faceMatchScore": 0.98,
"passed": true,
"timestamp": "2025-01-27T10:30:00Z"
},
"riskAssessment": {
"riskLevel": "low"
},
"verifiedFields": [
"firstName",
"lastName",
"dateOfBirth",
"nationality",
"documentNumber",
"documentType"
],
"warnings": [],
"verifiedAt": "2025-01-27T10:30:00Z",
"createdAt": "2025-01-27T09:00:00Z",
"updatedAt": "2025-01-27T10:30:00Z",
"metadata": {
"integrationCode": "global_gueno_validation_kyc",
"integrationName": "Gu1 KYC"
}
}
```
## Example Request
```javascript Node.js theme={null}
const entityId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/entities/${entityId}/current`,
{
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
},
}
);
const validation = await response.json();
console.log('Current validation status:', validation.status);
console.log('Verified at:', validation.verifiedAt);
```
```python Python theme={null}
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',
}
)
validation = response.json()
print('Current validation status:', validation['status'])
print('Verified at:', validation.get('verifiedAt'))
```
```curl cURL theme={null}
curl -X GET https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/current \
-H "Authorization: Bearer YOUR_API_KEY"
```
## Status Values
The response `status` field can be one of:
* **`pending`** - Validation created, customer hasn't started
* **`in_progress`** - Customer is completing verification (filling out form)
* **`in_review`** - Verification completed, requires manual review from compliance team
* **`approved`** - Verification successful (by provider or manually)
* **`rejected`** - Verification failed (by provider or manually)
* **`expired`** - Validation expired (customer didn't complete in time)
* **`abandoned`** - Customer started but didn't complete
* **`cancelled`** - Validation manually cancelled
## Error Responses
### No Current Validation Found (404)
```json theme={null}
{
"error": "NOT_FOUND",
"message": "No current KYC validation found for this entity"
}
```
This means the entity either:
* Has never had a KYC validation created
* Has validations, but none are marked as current (`isCurrent: false`)
* All validations are in terminal states (cancelled, expired, etc.)
### Entity Not Found (404)
```json theme={null}
{
"error": "ENTITY_NOT_FOUND",
"message": "Entity not found"
}
```
## Important Notes
If the validation images are older than 3.5 hours, this endpoint automatically syncs with the KYC provider to refresh the data. This ensures you always get fresh verification images and data.
Only one validation per entity can have `isCurrent: true` at a time. When a new validation is created, the previous current validation is automatically marked as not current. Use the `/api/kyc/entities/:entityId/validations` endpoint to retrieve historical validations.
Possible status values:
* `pending`: User hasn't started verification yet
* `in_progress`: User is completing verification (has some data but not finished)
* `approved`: Verification approved (by provider or manually)
* `rejected`: Verification rejected (by provider or manually)
* `cancelled`: Validation was cancelled
* `expired`: Validation expired (user didn't complete in time)
* `abandoned`: User started but abandoned the verification process
If a validation has been manually approved, rejected, or cancelled, it will NOT be updated by provider webhooks or sync operations. Manual decisions are protected to maintain audit trail integrity.
## Next Steps
Start a new verification session
View validation history for an entity
Manually refresh validation data
Manually approve a validation