List KYC Validations for Entity

Overview

This endpoint retrieves the complete history of KYC validations for a specific entity. This is useful for auditing, compliance tracking, and understanding an entity’s verification journey. Key features:

Returns all validations (current and historical) for an entity
Supports pagination for large validation histories
Includes full verification details for each validation
Ordered by creation date (most recent first)
Shows which validation is currently active

When to Use This

Audit verification history: View all KYC attempts and their outcomes
Compliance reporting: Track verification attempts for regulatory compliance
User support: Investigate why a user’s verification failed or succeeded
Analytics: Analyze verification success rates and abandonment patterns
Debugging: Troubleshoot verification issues by reviewing the full history

Request

Endpoint

GET https://api.gu1.ai/api/kyc/entities/{entityId}/validations

Path Parameters

entityId

string

required

The UUID of the entity to retrieve validations for

Query Parameters

page

integer

default:"1"

Page number for pagination (starts at 1)

limit

integer

default:"100"

Number of validations per page (max 100)

status

string

Filter validations by status. Possible values:

pending - Validation created, user hasn’t started
in_progress - User is actively completing verification (filling out form)
in_review - Verification completed, requires manual review from compliance team
approved - Verification successful
rejected - Verification failed
expired - Validation expired (user didn’t complete in time)
abandoned - User started but didn’t complete
cancelled - Validation was cancelled by organization

isCurrent

boolean

Filter to show only the current active validation (true) or historical validations (false)

Headers

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Response

Success Response (200 OK)

Returns a paginated list of validations:

{
  "validations": [
    {
      "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",
        "features": ["id_verification", "liveness", "face_match"],
        "id_verification": {
          "status": "Approved",
          "document_type": "Passport",
          "full_name": "John Doe",
          "date_of_birth": "1990-01-15"
        }
      },
      "extractedData": {
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-01-15",
        "documentType": "Passport"
      },
      "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"
      }
    },
    {
      "id": "440e8400-e29b-41d4-a716-446655440001",
      "entityId": "123e4567-e89b-12d3-a456-426614174000",
      "organizationId": "org_abc123",
      "validationSessionId": "session_abc456",
      "status": "abandoned",
      "provider": "Gu1 KYC",
      "providerSessionUrl": "https://verify.example.com/session_abc456",
      "isCurrent": false,
      "decision": null,
      "extractedData": null,
      "verifiedAt": null,
      "createdAt": "2025-01-20T14:00:00Z",
      "updatedAt": "2025-01-21T10:00:00Z",
      "metadata": {
        "integrationCode": "global_gueno_validation_kyc",
        "integrationName": "Gu1 KYC"
      }
    }
  ],
  "total": 2,
  "page": 1,
  "limit": 100
}

Response Fields

validations

array

Array of validation objects

total

integer

Total number of validations matching the query

page

integer

Current page number

limit

integer

Number of validations per page

Example Requests

Get All Validations for Entity

const entityId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

const result = await response.json();
console.log(`Found ${result.total} validations`);
console.log(`Current page: ${result.page} of ${Math.ceil(result.total / result.limit)}`);

result.validations.forEach(validation => {
  console.log(`${validation.id}: ${validation.status} (${validation.isCurrent ? 'current' : 'historical'})`);
});

Filter by Status

Get only approved validations:

const entityId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?status=approved`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

const result = await response.json();
console.log(`Found ${result.total} approved validations`);

Get Only Current Validation

const entityId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?isCurrent=true`,
  {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
    },
  }
);

const result = await response.json();

if (result.validations.length > 0) {
  const currentValidation = result.validations[0];
  console.log('Current validation status:', currentValidation.status);
} else {
  console.log('No current validation found');
}

Pagination Example

const entityId = '123e4567-e89b-12d3-a456-426614174000';

async function getAllValidations(entityId) {
  let page = 1;
  const limit = 50;
  let allValidations = [];

  while (true) {
    const response = await fetch(
      `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?page=${page}&limit=${limit}`,
      {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
        },
      }
    );

    const result = await response.json();
    allValidations = allValidations.concat(result.validations);

    console.log(`Fetched page ${page}: ${result.validations.length} validations`);

    // Check if we've fetched all validations
    if (allValidations.length >= result.total) {
      break;
    }

    page++;
  }

  return allValidations;
}

const validations = await getAllValidations(entityId);
console.log(`Total validations fetched: ${validations.length}`);

Error Responses

Entity Not Found (404)

{
  "error": "NOT_FOUND",
  "message": "Entity not found"
}

Invalid Query Parameters (400)

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid status value. Must be one of: pending, in_progress, approved, rejected, expired, abandoned, cancelled"
}

Unauthorized (401)

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}

Use Cases

1. Audit Trail for Compliance

Track all verification attempts for regulatory compliance:

async function getVerificationAuditTrail(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();

  // Generate audit report
  const auditReport = result.validations.map(v => ({
    validationId: v.id,
    status: v.status,
    provider: v.provider,
    createdAt: v.createdAt,
    completedAt: v.verifiedAt || v.updatedAt,
    isCurrent: v.isCurrent,
    manualAction: v.metadata?.manuallyApprovedBy || v.metadata?.manuallyRejectedBy,
  }));

  return auditReport;
}

2. Calculate Success Rate

Analyze verification success rates:

async function calculateSuccessRate(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();
  const validations = result.validations;

  const completed = validations.filter(v =>
    ['approved', 'rejected'].includes(v.status)
  );

  const approved = validations.filter(v => v.status === 'approved');
  const rejected = validations.filter(v => v.status === 'rejected');
  const abandoned = validations.filter(v => v.status === 'abandoned');

  return {
    total: validations.length,
    completed: completed.length,
    approved: approved.length,
    rejected: rejected.length,
    abandoned: abandoned.length,
    successRate: completed.length > 0
      ? (approved.length / completed.length * 100).toFixed(2) + '%'
      : 'N/A',
    abandonmentRate: validations.length > 0
      ? (abandoned.length / validations.length * 100).toFixed(2) + '%'
      : 'N/A',
  };
}

3. Find Failed Validations for Support

Help users who had verification issues:

async function findFailedValidations(entityId) {
  const response = await fetch(
    `https://api.gu1.ai/api/kyc/entities/${entityId}/validations?status=rejected`,
    {
      headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
    }
  );

  const result = await response.json();

  // Extract failure reasons
  const failures = result.validations.map(v => ({
    validationId: v.id,
    rejectedAt: v.updatedAt,
    reason: v.metadata?.rejectionReason || 'Not specified',
    warnings: v.warnings || [],
    decision: v.decision,
  }));

  return failures;
}

4. Export Validation History

Export complete validation history for reporting:

async function exportValidationHistory(entityId) {
  const validations = await getAllValidations(entityId); // From pagination example

  // Convert to CSV format
  const csv = [
    'Validation ID,Status,Provider,Created At,Verified At,Is Current',
    ...validations.map(v =>
      `${v.id},${v.status},${v.provider},${v.createdAt},${v.verifiedAt || ''},${v.isCurrent}`
    )
  ].join('\n');

  return csv;
}

Important Notes

Default Pagination

By default, this endpoint returns up to 100 validations per page. If an entity has more than 100 validations, you’ll need to use pagination to retrieve all records.

Ordering

Validations are returned in descending order by creation date (most recent first). The current validation will typically appear first in the list.

isCurrent Flag

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 isCurrent: false.

Historical Data Retention

All validations are retained indefinitely for audit and compliance purposes. Historical validations are never deleted, even if they’re abandoned or expired.

Performance Considerations

For entities with many validations (>100), consider using pagination and status filters to reduce response size and improve performance.

Differences from Similar Endpoints

Endpoint	Purpose	Use Case
`GET /api/kyc/entities/:entityId/validations`	Get all validations for an entity	Audit trail, history, analytics
`GET /api/kyc/entities/:entityId/current`	Get only current validation	Check if user is verified right now
`GET /api/kyc/validations/:id`	Get specific validation by ID	Retrieve details of a known validation
`GET /api/kyc/validations`	List all validations across all entities	Organization-wide analytics

Next Steps

Get Current Validation

Get only the active validation for an entity

Create KYC Validation

Start a new verification session

Check Entity Status

Get entity verification status summary

Sync Validation

Manually refresh validation data

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

​When to Use This

​Request

​Endpoint

​Path Parameters

​Query Parameters

​Headers

​Response

​Success Response (200 OK)

​Response Fields

​Example Requests

​Get All Validations for Entity

​Filter by Status

​Get Only Current Validation

​Pagination Example

​Error Responses

​Entity Not Found (404)

​Invalid Query Parameters (400)

​Unauthorized (401)

​Use Cases

​1. Audit Trail for Compliance

​2. Calculate Success Rate

​3. Find Failed Validations for Support

​4. Export Validation History

​Important Notes

​Differences from Similar Endpoints

​Next Steps

Get Current Validation

Create KYC Validation

Check Entity Status

Sync Validation

Overview

When to Use This

Request

Endpoint

Path Parameters

Query Parameters

Headers

Response

Success Response (200 OK)

Response Fields

Example Requests

Get All Validations for Entity

Filter by Status

Get Only Current Validation

Pagination Example

Error Responses

Entity Not Found (404)

Invalid Query Parameters (400)

Unauthorized (401)

Use Cases

1. Audit Trail for Compliance

2. Calculate Success Rate

3. Find Failed Validations for Support

4. Export Validation History

Important Notes

Differences from Similar Endpoints

Next Steps