Skip to main content
GET
/
api
/
kyc
/
entities
/
{entityId}
/
current
Get Current KYC Validation
curl --request GET \
  --url http://api.gu1.ai/api/kyc/entities/{entityId}/current \
  --header 'Authorization: Bearer <token>'

​
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

​
entityId
string
required
The ID of the entity to get the current validation for

​
Headers

{
  "Authorization": "Bearer YOUR_API_KEY"
}

​
Response

​
Success Response (200 OK)

Returns the current validation object with all verification data: 
{
  "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

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);

​
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)

{
  "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)

{
  "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

Create KYC Validation

Start a new verification session

List All Validations

View validation history for an entity

Sync Validation

Manually refresh validation data

Approve Validation

Manually approve a validation