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

# Reject KYC Validation

> Manually reject a KYC validation — in the gu1 KYC API for identity verification flows, with examples for reject validation use cases.

## Overview

This endpoint allows you to manually reject a KYC validation. When you reject:

* **Automatic sync with provider**: The system first syncs with the KYC provider to get the latest verification status
* **Status validation**: You can only reject if provider status is `in_review` (user has completed verification and requires manual review from compliance team)
* The validation status changes to `rejected`
* The validation is marked as not current (`isCurrent: false`)
* The rejection reason is saved in metadata and audit logs

<Warning>
  Manual rejection should only be used when you've identified fraud risk, policy violations, or other legitimate reasons to deny the verification. The rejection reason is required for audit compliance.
</Warning>

## When to Use This

* **Fraudulent documents detected**: Documents appear fake, altered, or stolen
* **Inconsistent data**: Information doesn't match across different sources
* **High risk detected**: Internal risk assessment flags concerns
* **Policy violation**: User doesn't meet your verification requirements
* **Sanction list match**: User appears on watchlists or sanction lists

## Request

### Endpoint

```
POST https://api.gu1.ai/api/kyc/validations/{id}/reject
```

### Path Parameters

<ParamField path="id" type="string" required>
  The validation ID to reject
</ParamField>

### Headers

```json theme={null}
{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}
```

### Body Parameters

<ParamField body="reason" type="string" required>
  Reason for manually rejecting the validation (minimum 5 characters)

  **Type**: `string` (min length: 5)

  **Example**: `"Document authenticity verification failed - suspected fraud"`
</ParamField>

## Response

### Success Response (200 OK)

Returns the updated validation object with `rejected` status:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "rejected",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": false,
  "metadata": {
    "manuallyRejectedBy": "user_123",
    "manuallyRejectedAt": "2025-01-27T10:30:00Z",
    "rejectionReason": "Document authenticity verification failed - suspected fraud"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-27T10:30:00Z"
}
```

## Example Request

<CodeGroup>
  ```javascript Node.js theme={null}
  const validationId = '550e8400-e29b-41d4-a716-446655440000';

  const response = await fetch(
    `https://api.gu1.ai/api/kyc/validations/${validationId}/reject`,
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        reason: 'Document authenticity verification failed - suspected fraud'
      })
    }
  );

  const rejected = await response.json();
  console.log('Validation rejected:', rejected.status);
  ```

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

  validation_id = '550e8400-e29b-41d4-a716-446655440000'

  response = requests.post(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}/reject',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'reason': 'Document authenticity verification failed - suspected fraud'
      }
  )

  rejected = response.json()
  print('Validation rejected:', rejected['status'])
  ```

  ```curl cURL theme={null}
  curl -X POST https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/reject \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "Document authenticity verification failed - suspected fraud"
    }'
  ```
</CodeGroup>

## Error Responses

### Validation Not Found (404)

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

### Invalid Status (400)

Validation can only be rejected if provider status is `in_review` (user has completed verification and requires manual review from compliance team):

```json theme={null}
{
  "error": "INVALID_STATUS",
  "message": "Cannot manually reject. Current status is \"approved\". Manual rejection is only allowed when status is \"in_review\" (validation requires manual review from compliance team)."
}
```

**What this means:**

* If the provider already approved (`approved`) or rejected (`rejected`) the validation, you cannot override that decision
* If the validation is `cancelled`, you cannot reject it
* If it's `expired` or `abandoned`, it also cannot be manually rejected
* If it's `in_progress`, the user is still filling out the verification form
* **You can only reject** when the provider reports the validation as `in_review` (user has completed all verification steps and requires manual review from compliance team)

### Invalid Reason (400)

Reason must be at least 5 characters:

```json theme={null}
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}
```

## Important Notes

<AccordionGroup>
  <Accordion title="Automatic Sync Before Rejection">
    Before rejecting, the system automatically syncs with the KYC provider to get the latest verification data. This ensures you're making decisions based on the most recent information.
  </Accordion>

  <Accordion title="Status Protection">
    You cannot reject validations that are already `approved`, `rejected`, or `cancelled`. These statuses are protected to maintain data integrity.
  </Accordion>

  <Accordion title="Audit Trail">
    The rejection reason is saved in both the validation metadata and audit logs. This is critical for compliance and regulatory requirements.
  </Accordion>

  <Accordion title="Only for In-Review Validations">
    Manual rejection is only allowed when the provider reports the validation as `in_review`. This prevents rejecting validations that:

    * The provider has already approved or completed
    * Don't have complete verification data (status `pending` or `in_progress`)
    * The user is still filling out the form (status `in_progress`)
  </Accordion>

  <Accordion title="No Verification Timestamp">
    When rejected, the validation does NOT receive a `verifiedAt` timestamp and is marked as not current for the entity.
  </Accordion>

  <Accordion title="Can Create New Validation">
    After rejection, the user can create a new KYC validation for the same entity if they want to retry verification.
  </Accordion>
</AccordionGroup>

## Best Practices

* **Be specific with reasons**: Clearly document why the validation was rejected
* **Follow fraud procedures**: Ensure rejection follows your internal fraud prevention protocols
* **Consider regulatory requirements**: Some jurisdictions require specific documentation for rejections
* **Review fresh data**: The automatic sync ensures you see the latest documents and biometric results
* **Document internally**: Maintain detailed notes about fraud indicators or policy violations
* **Train your team**: Ensure staff understand rejection criteria and when to escalate

## Next Steps

<CardGroup cols={2}>
  <Card title="Approve Validation" icon="check" href="/en/use-cases/kyc/approve-validation">
    Manually approve a validation
  </Card>

  <Card title="Check Verification Status" icon="magnifying-glass" href="/en/use-cases/kyc/check-status">
    Query validation results
  </Card>
</CardGroup>