Get KYC Verification URL

curl --request GET \
  --url http://api.gu1.ai/api/kyc/validations/{id} \
  --header 'Authorization: Bearer <token>'

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

}

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>"
}

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>'

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

}

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 start
in_progress - Customer is completing verification
in_review - Verification completed, requires manual review from compliance team
approved - Verification successful
rejected - Verification failed
expired - Session expired
abandoned - Customer abandoned the process
cancelled - Validation was cancelled

object

Final decision details (available after completion):

document_details - Information about verified document
extracted_information - Personal data extracted from document
verification_results - Results of various checks
warnings - 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']

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"
}

This can happen if:

The validation ID doesn’t exist
The validation belongs to a different organization
The validation was deleted

Best Practices

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

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

Verification URLs typically expire after 7 days. If a customer’s session expires, create a new validation.

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

Sandbox mock data Get Current KYC Validation

⌘I

​Overview

​When to Use This

​Request

​Endpoint

​Path Parameters

​Headers

​Response

​Success Response (200 OK)

​Response Fields

​Example Request

​Alternative: Get Current Validation for Entity

​Endpoint

​Example

​Sharing the URL with Customers

​Email Example

​SMS Example

​In-App Integration

​Error Responses

​Validation Not Found (404)

​Best Practices

​Next Steps

Webhook Integration

Check Verification Status

Overview

When to Use This

Request

Endpoint

Path Parameters

Headers

Response

Success Response (200 OK)

Response Fields

Example Request

Alternative: Get Current Validation for Entity

Endpoint

Example

Sharing the URL with Customers

Email Example

SMS Example

In-App Integration

Error Responses

Validation Not Found (404)

Best Practices

Next Steps