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

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

​
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

​
id
string
required
The validation ID to reject

​
Headers

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

​
Body Parameters

​
reason
string
required
Reason for manually rejecting the validation (minimum 5 characters)Type: string (min length: 5)Example: "Document authenticity verification failed - suspected fraud"

​
Response

​
Success Response (200 OK)

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

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

​
Error Responses

​
Validation Not Found (404)

{
  "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): 
{
  "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: 
{
  "error": "VALIDATION_ERROR",
  "message": "Reason must be at least 5 characters"
}

​
Important Notes

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.
You cannot reject validations that are already approved, rejected, or cancelled. These statuses are protected to maintain data integrity.
The rejection reason is saved in both the validation metadata and audit logs. This is critical for compliance and regulatory requirements.
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)
When rejected, the validation does NOT receive a verifiedAt timestamp and is marked as not current for the entity.
After rejection, the user can create a new KYC validation for the same entity if they want to retry verification.

​
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

Approve Validation

Manually approve a validation

Check Verification Status

Query validation results