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

# Cancel KYC Validation

> Cancel a pending, in-progress, or in-review KYC validation — in the gu1 KYC API for identity verification flows, with examples for cancel validation use cases.

## Overview

This endpoint allows you to cancel a KYC validation that is in `pending`, `in_progress`, or `in_review` status. When cancelled:

* The validation status changes to `cancelled`
* The provider session is terminated (user cannot access the verification URL anymore)
* The validation is marked as not current (`isCurrent: false`)
* You can create a new validation for the same entity afterward

<Warning>
  This action cannot be undone. The user will need to start a new validation process if they still need to verify their identity.
</Warning>

## When to Use This

* **User requested cancellation**: Customer no longer wants to complete verification
* **Incorrect data**: Entity information was entered incorrectly
* **Duplicate validation**: Validation was created by mistake
* **Process restart needed**: Need to start fresh with new verification session

## Request

### Endpoint

```
DELETE https://api.gu1.ai/api/kyc/validations/{id}/cancel
```

### Path Parameters

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

### Headers

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

### Body Parameters

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

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

  **Example**: `"User requested to cancel the verification process"`
</ParamField>

## Response

### Success Response (200 OK)

Returns the updated validation object with `cancelled` status:

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "validationSessionId": "session_xyz789",
  "status": "cancelled",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": false,
  "metadata": {
    "cancelledBy": "user_123",
    "cancelledAt": "2025-01-27T10:30:00Z",
    "cancellationReason": "User requested to cancel the verification process"
  },
  "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}/cancel`,
    {
      method: 'DELETE',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        reason: 'User requested to cancel the verification process'
      })
    }
  );

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

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

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

  response = requests.delete(
      f'https://api.gu1.ai/api/kyc/validations/{validation_id}/cancel',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json',
      },
      json={
          'reason': 'User requested to cancel the verification process'
      }
  )

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

  ```curl cURL theme={null}
  curl -X DELETE https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000/cancel \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "reason": "User requested to cancel the verification process"
    }'
  ```
</CodeGroup>

## Error Responses

### Validation Not Found (404)

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

### Invalid Status (400)

Validation can only be cancelled if status is `pending`, `in_progress`, or `in_review`:

```json theme={null}
{
  "error": "INVALID_STATUS",
  "message": "Cannot cancel validation with status 'approved'. Only 'pending', 'in_progress', or 'in_review' validations can be cancelled."
}
```

### 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="Session is Deleted from Provider">
    When you cancel a validation, we attempt to delete the session from the KYC provider. The verification URL will no longer work for the user.
  </Accordion>

  <Accordion title="Audit Trail">
    The cancellation reason is saved in the validation metadata and audit logs. This helps maintain compliance and track why validations were cancelled.
  </Accordion>

  <Accordion title="Cannot Cancel Completed Validations">
    You cannot cancel validations that are already `approved`, `rejected`, `expired`, `abandoned`, or `cancelled`. Only `pending`, `in_progress`, or `in_review` validations can be cancelled.
  </Accordion>

  <Accordion title="Create New Validation After Cancellation">
    After cancelling, you can create a new KYC validation for the same entity. The previous validation will remain in the history with `cancelled` status.
  </Accordion>
</AccordionGroup>

## Next Steps

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

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