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>"
}
'import requests
url = "http://api.gu1.ai/api/kyc/validations/{id}/reject"
payload = { "reason": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: '<string>'})
};
fetch('http://api.gu1.ai/api/kyc/validations/{id}/reject', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations/{id}/reject",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations/{id}/reject"
payload := strings.NewReader("{\n \"reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/validations/{id}/reject")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations/{id}/reject")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodySession-based validation
Reject KYC Validation
Manually reject a KYC validation — in the gu1 KYC API for identity verification flows, with examples for reject validation use cases.
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>"
}
'import requests
url = "http://api.gu1.ai/api/kyc/validations/{id}/reject"
payload = { "reason": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({reason: '<string>'})
};
fetch('http://api.gu1.ai/api/kyc/validations/{id}/reject', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/api/kyc/validations/{id}/reject",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'reason' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations/{id}/reject"
payload := strings.NewReader("{\n \"reason\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("http://api.gu1.ai/api/kyc/validations/{id}/reject")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"reason\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations/{id}/reject")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"reason\": \"<string>\"\n}"
response = http.request(request)
puts response.read_bodyOverview
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
string
required
The validation ID to reject
Headers
{
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}
Body Parameters
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 withrejected 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);
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 -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"
}'
Error Responses
Validation Not Found (404)
{
"error": "NOT_FOUND",
"message": "Validation not found"
}
Invalid Status (400)
Validation can only be rejected if provider status isin_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)."
}
- 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
expiredorabandoned, 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
Automatic Sync Before Rejection
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.
Status Protection
Status Protection
You cannot reject validations that are already
approved, rejected, or cancelled. These statuses are protected to maintain data integrity.Audit Trail
Audit Trail
The rejection reason is saved in both the validation metadata and audit logs. This is critical for compliance and regulatory requirements.
Only for In-Review Validations
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
pendingorin_progress) - The user is still filling out the form (status
in_progress)
No Verification Timestamp
No Verification Timestamp
When rejected, the validation does NOT receive a
verifiedAt timestamp and is marked as not current for the entity.Can Create New Validation
Can Create New Validation
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
Was this page helpful?