Skip to main content
GET
http://api.gu1.ai
/
api
/
kyc
/
validations
/
{id}
Get KYC Verification URL
curl --request GET \
  --url http://api.gu1.ai/api/kyc/validations/{id} \
  --header 'Authorization: Bearer <token>'
{
  "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

​
id
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",
  "sessionId": "session_xyz789",
  "status": "pending",
  "metadata",
  "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

​
providerSessionUrl
string
The verification URL to share with your customer. This is the main field you need.
​
status
string
Current validation status:
  • pending - Waiting for customer to start
  • in_progress - Customer is completing verification
  • approved - Verification successful
  • rejected - Verification failed
  • expired - Session expired
  • abandoned - Customer abandoned the process
​
decision
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
​
documentsVerified
array
List of documents that were verified (after completion)
​
biometricResult
object
Results of biometric verification (after completion)
​
riskAssessment
object
Risk assessment information (after completion)
​
verifiedFields
array
List of fields successfully verified (e.g., [“firstName”, “lastName”, “dateOfBirth”])
​
extractedData
object
Personal data extracted from the document
​
verifiedAt
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);

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

​
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"
}
This can happen if:
  • The validation ID doesn’t exist
  • The validation belongs to a different organization
  • The validation was deleted

​
Best Practices

Always store the validation ID in your database linked to your customer record. This allows you to retrieve the validation details later.
The verification URL is sensitive and should only be shared with the intended customer. Don’t expose it in public APIs or URLs.
Verification URLs typically expire after 7 days. If a customer’s session expires, create a new validation.
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