> ## 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.

# List KYC Validations for Entity

> Retrieve all KYC validation history for a specific entity — in the gu1 KYC API for identity verification flows, with examples for list validations use cases.

## 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

<ParamField path="entityId" type="string" required>
  The UUID of the entity to retrieve validations for
</ParamField>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number for pagination (starts at 1)
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Number of validations per page (max 100)
</ParamField>

<ParamField query="status" type="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
</ParamField>

<ParamField query="isCurrent" type="boolean">
  Filter to show only the current active validation (`true`) or historical validations (`false`)
</ParamField>

### Headers

```json theme={null}
{
  "Authorization": "Bearer YOUR_API_KEY"
}
```

## Response

### Success Response (200 OK)

Returns a paginated list of validations:

```json theme={null}
{
  "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",
      "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",
        "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

<ResponseField name="validations" type="array">
  Array of validation objects
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of validations matching the query
</ResponseField>

<ResponseField name="page" type="integer">
  Current page number
</ResponseField>

<ResponseField name="limit" type="integer">
  Number of validations per page
</ResponseField>

## Example Requests

### Get All Validations for Entity

<CodeGroup>
  ```javascript Node.js theme={null}
  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'})`);
  });
  ```

  ```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}/validations',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
      }
  )

  result = response.json()
  print(f"Found {result['total']} validations")
  print(f"Current page: {result['page']} of {result['total'] // result['limit'] + 1}")

  for validation in result['validations']:
      current_status = 'current' if validation['isCurrent'] else 'historical'
      print(f"{validation['id']}: {validation['status']} ({current_status})")
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/validations" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

### Filter by Status

Get only approved validations:

<CodeGroup>
  ```javascript Node.js theme={null}
  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`);
  ```

  ```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}/validations',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'status': 'approved'}
  )

  result = response.json()
  print(f"Found {result['total']} approved validations")
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/validations?status=approved" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

### Get Only Current Validation

<CodeGroup>
  ```javascript Node.js theme={null}
  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');
  }
  ```

  ```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}/validations',
      headers={'Authorization': 'Bearer YOUR_API_KEY'},
      params={'isCurrent': 'true'}
  )

  result = response.json()

  if result['validations']:
      current_validation = result['validations'][0]
      print(f"Current validation status: {current_validation['status']}")
  else:
      print('No current validation found')
  ```

  ```curl cURL theme={null}
  curl -X GET "https://api.gu1.ai/api/kyc/entities/123e4567-e89b-12d3-a456-426614174000/validations?isCurrent=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

### Pagination Example

<CodeGroup>
  ```javascript Node.js theme={null}
  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}`);
  ```

  ```python Python theme={null}
  import requests

  def get_all_validations(entity_id, api_key):
      page = 1
      limit = 50
      all_validations = []

      while True:
          response = requests.get(
              f'https://api.gu1.ai/api/kyc/entities/{entity_id}/validations',
              headers={'Authorization': f'Bearer {api_key}'},
              params={'page': page, 'limit': limit}
          )

          result = response.json()
          all_validations.extend(result['validations'])

          print(f"Fetched page {page}: {len(result['validations'])} validations")

          # Check if we've fetched all validations
          if len(all_validations) >= result['total']:
              break

          page += 1

      return all_validations

  entity_id = '123e4567-e89b-12d3-a456-426614174000'
  validations = get_all_validations(entity_id, 'YOUR_API_KEY')
  print(f"Total validations fetched: {len(validations)}")
  ```
</CodeGroup>

## Error Responses

### Entity Not Found (404)

```json theme={null}
{
  "error": "NOT_FOUND",
  "message": "Entity not found"
}
```

### Invalid Query Parameters (400)

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

### Unauthorized (401)

```json theme={null}
{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing API key"
}
```

## Use Cases

### 1. Audit Trail for Compliance

Track all verification attempts for regulatory compliance:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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:

```javascript theme={null}
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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Ordering">
    Validations are returned in descending order by creation date (most recent first). The current validation will typically appear first in the list.
  </Accordion>

  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Performance Considerations">
    For entities with many validations (>100), consider using pagination and status filters to reduce response size and improve performance.
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Get Current Validation" icon="check-circle" href="/en/use-cases/kyc/current-validation">
    Get only the active validation for an entity
  </Card>

  <Card title="Create KYC Validation" icon="play" href="/en/use-cases/kyc/create-validation">
    Start a new verification session
  </Card>

  <Card title="Check Entity Status" icon="shield-check" href="/en/use-cases/kyc/check-status">
    Get entity verification status summary
  </Card>

  <Card title="Sync Validation" icon="arrows-rotate" href="/en/use-cases/kyc/sync-validation">
    Manually refresh validation data
  </Card>
</CardGroup>