Check Verification Status

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

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

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

Understanding Validation Results

Status Values

status

string

Current validation status:

pending - Validation created, waiting for customer to start
in_progress - Customer is actively completing verification (filling out form)
in_review - Verification completed, requires manual review from compliance team
approved - Verification successful, identity confirmed
rejected - Verification failed, identity not confirmed
expired - Verification session expired (typically after 7 days)
abandoned - Customer started but didn’t complete verification
cancelled - Validation manually cancelled

Decision Object

When status is approved or rejected, the decision field contains detailed results:

{
  "decision": {
    "document_details": {
      "type": "passport",
      "number": "AB123456",
      "country": "US",
      "issueDate": "2020-01-15",
      "expiryDate": "2030-01-15"
    },
    "extracted_information": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-05-20",
      "nationality": "US",
      "address": "123 Main St, New York, NY 10001"
    },
    "verification_results": {
      "documentAuthenticity": "pass",
      "faceMatch": "pass",
      "liveness": "pass",
      "aml": "clear"
    },
    "warnings": [
      "Document expiring within 6 months"
    ],
    "reviewer_comments": null
  }
}

Verification Results

Each verification check has a result:

Check	Description	Possible Values
`documentAuthenticity`	Is the document genuine?	`pass`, `fail`, `pending`
`faceMatch`	Does selfie match document photo?	`pass`, `fail`, `pending`
`liveness`	Is the person real (not a photo/video)?	`pass`, `fail`, `pending`
`aml`	Sanctions/watchlist screening	`clear`, `match`, `pending`

Extracted Data

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

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

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

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

Verifications may expire after a certain period (typically 1 year). Check needsReverification and prompt customers to reverify when necessary.

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.

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Get Validation by ID

​Endpoint

​Example

​Get Current Validation for Entity

​Endpoint

​Example

​Get Entity KYC Status

​Endpoint

​Response

​Example

​Understanding Validation Results

​Status Values

​Decision Object

​Verification Results

​Extracted Data

​List All Validations for Entity

​Endpoint

​Response

​Sync Validation Status

​Endpoint

​Example

​Common Integration Patterns

​Pattern 1: Check Before Allowing Action

​Pattern 2: Conditional Features Based on Verification

​Pattern 3: Periodic Re-verification Check

​Best Practices

​Next Steps

Create KYC Validation

Webhook Integration

Overview

Get Validation by ID

Endpoint

Example

Get Current Validation for Entity

Endpoint

Example

Get Entity KYC Status

Endpoint

Response

Example

Understanding Validation Results

Status Values

Decision Object

Verification Results

Extracted Data

List All Validations for Entity

Endpoint

Response

Sync Validation Status

Endpoint

Example

Common Integration Patterns

Pattern 1: Check Before Allowing Action

Pattern 2: Conditional Features Based on Verification

Pattern 3: Periodic Re-verification Check

Best Practices

Next Steps