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