Skip to main content
DELETE
/
api
/
kyc
/
validations
/
{id}
/
cancel
Cancel KYC Validation
curl --request DELETE \
  --url http://api.gu1.ai/api/kyc/validations/{id}/cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>"
}
'

​
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
This action cannot be undone. The user will need to start a new validation process if they still need to verify their identity.

​
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

​
id
string
required
The validation ID to cancel

​
Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

​
Body Parameters

​
reason
string
required
Reason for cancelling the validation (minimum 5 characters)Type: string (min length: 5)Example: "User requested to cancel the verification process"

​
Response

​
Success Response (200 OK)

Returns the updated validation object with cancelled status: 
{
  "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

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

​
Error Responses

​
Validation Not Found (404)

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

​
Invalid Status (400)

Validation can only be cancelled if status is pending, in_progress, or in_review: 
{
  "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: 
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}

​
Important Notes

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.
The cancellation reason is saved in the validation metadata and audit logs. This helps maintain compliance and track why validations were cancelled.
You cannot cancel validations that are already approved, rejected, expired, abandoned, or cancelled. Only pending, in_progress, or in_review validations can be cancelled.
After cancelling, you can create a new KYC validation for the same entity. The previous validation will remain in the history with cancelled status.

​
Next Steps

Create KYC Validation

Start a new verification session

Check Verification Status

Query validation results