Get KYC Verification URL
curl --request GET \
--url http://api.gu1.ai/api/kyc/validations/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/api/kyc/validations/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/api/kyc/validations/{id}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/api/kyc/validations/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations/{id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"providerSessionUrl": "<string>",
"status": "<string>",
"decision": {},
"documentsVerified": [
{}
],
"biometricResult": {},
"riskAssessment": {},
"verifiedFields": [
{}
],
"extractedData": {},
"verifiedAt": "<string>"
}Session-based validation
Get KYC Verification URL
Retrieve the verification URL to share with your customer — in the gu1 KYC API for identity verification flows, with examples for get kyc url use cases.
GET
/
api
/
kyc
/
validations
/
{id}
Get KYC Verification URL
curl --request GET \
--url http://api.gu1.ai/api/kyc/validations/{id} \
--header 'Authorization: Bearer <token>'import requests
url = "http://api.gu1.ai/api/kyc/validations/{id}"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('http://api.gu1.ai/api/kyc/validations/{id}', 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}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "http://api.gu1.ai/api/kyc/validations/{id}"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("http://api.gu1.ai/api/kyc/validations/{id}")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/api/kyc/validations/{id}")
http = Net::HTTP.new(url.host, url.port)
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"providerSessionUrl": "<string>",
"status": "<string>",
"decision": {},
"documentsVerified": [
{}
],
"biometricResult": {},
"riskAssessment": {},
"verifiedFields": [
{}
],
"extractedData": {},
"verifiedAt": "<string>"
}Overview
After creating a KYC validation, you can retrieve the verification URL at any time. This URL is what you’ll share with your customer so they can complete the identity verification process.When to Use This
- Retrieve URL later: If you didn’t store the URL from the creation response
- Resend to customer: When customer requests a new link
- Check validation details: View current status and metadata
- Integrate with other systems: Pass verification URL to notification services
Request
Endpoint
GET https://api.gu1.ai/api/kyc/validations/{id}
Path Parameters
string
required
The validation ID returned when you created the KYC validation
Headers
{
"Authorization": "Bearer YOUR_API_KEY"
}
Response
Success Response (200 OK)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"entityId": "123e4567-e89b-12d3-a456-426614174000",
"organizationId": "org_abc123",
"validationSessionId": "session_xyz789",
"status": "pending",
"provider": "kyc_provider",
"providerSessionUrl": "https://verify.example.com/session_xyz789",
"decision": null,
"documentsVerified": [],
"biometricResult": null,
"riskAssessment": null,
"verifiedFields": [],
"extractedData": null,
"warnings": [],
"isCurrent": true,
"expiresAt": null,
"verifiedAt": null,
"metadata": {
"userId": "user_12345",
"source": "mobile_app"
},
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-15T10:30:00Z"
}
Response Fields
string
The verification URL to share with your customer. This is the main field you need.
string
Current validation status:
pending- Waiting for customer to startin_progress- Customer is completing verificationin_review- Verification completed, requires manual review from compliance teamapproved- Verification successfulrejected- Verification failedexpired- Session expiredabandoned- Customer abandoned the processcancelled- Validation was cancelled
object
Final decision details (available after completion):
document_details- Information about verified documentextracted_information- Personal data extracted from documentverification_results- Results of various checkswarnings- Any warnings or issues found
array
List of documents that were verified (after completion)
object
Results of biometric verification (after completion)
object
Risk assessment information (after completion)
array
List of fields successfully verified (e.g., [“firstName”, “lastName”, “dateOfBirth”])
object
Personal data extracted from the document
string
Timestamp when verification was completed
Example Request
const validationId = '550e8400-e29b-41d4-a716-446655440000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/validations/${validationId}`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const validation = await response.json();
// Extract the URL to share with customer
const verificationUrl = validation.providerSessionUrl;
console.log('Share this URL with your customer:', verificationUrl);
// Check current status
console.log('Current status:', validation.status);
import requests
validation_id = '550e8400-e29b-41d4-a716-446655440000'
response = requests.get(
f'https://api.gu1.ai/api/kyc/validations/{validation_id}',
headers={
'Authorization': 'Bearer YOUR_API_KEY'
}
)
validation = response.json()
# Extract the URL to share with customer
verification_url = validation['providerSessionUrl']
print('Share this URL with your customer:', verification_url)
# Check current status
print('Current status:', validation['status'])
curl -X GET https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer YOUR_API_KEY"
Alternative: Get Current Validation for Entity
If you don’t have the validation ID but have the entity ID, you can get the current validation:Endpoint
GET https://api.gu1.ai/api/kyc/entities/{entityId}/current
Example
const entityId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(
`https://api.gu1.ai/api/kyc/entities/${entityId}/current`,
{
headers: {
'Authorization': 'Bearer YOUR_API_KEY'
}
}
);
const validation = await response.json();
const verificationUrl = validation.providerSessionUrl;
entity_id = '123e4567-e89b-12d3-a456-426614174000'
response = requests.get(
f'https://api.gu1.ai/api/kyc/entities/{entity_id}/current',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
validation = response.json()
verification_url = validation['providerSessionUrl']
Sharing the URL with Customers
Once you have the verification URL, you can share it with your customer through various channels:Email Example
<p>Hi {{customerName}},</p>
<p>Please complete your identity verification to continue:</p>
<p><a href="{{providerSessionUrl}}">Verify Your Identity</a></p>
<p>This link will expire in 7 days.</p>
SMS Example
Complete your identity verification here: {{providerSessionUrl}}
In-App Integration
// Redirect user to verification
window.location.href = providerSessionUrl;
// Or open in new window
window.open(providerSessionUrl, '_blank');
// Or embed in iframe
<iframe src={providerSessionUrl} width="100%" height="600px" />
Error Responses
Validation Not Found (404)
{
"error": "NOT_FOUND",
"message": "KYC validation not found"
}
- The validation ID doesn’t exist
- The validation belongs to a different organization
- The validation was deleted
Best Practices
Store the Validation ID
Store the Validation ID
Always store the validation ID in your database linked to your customer record. This allows you to retrieve the validation details later.
Don't Expose URLs Publicly
Don't Expose URLs Publicly
The verification URL is sensitive and should only be shared with the intended customer. Don’t expose it in public APIs or URLs.
Handle Expired Sessions
Handle Expired Sessions
Verification URLs typically expire after 7 days. If a customer’s session expires, create a new validation.
Monitor Status Changes
Monitor Status Changes
Use webhooks to receive real-time notifications when the verification status changes, rather than polling this endpoint.
Next Steps
Webhook Integration
Receive real-time status updates
Check Verification Status
Query validation results
Was this page helpful?