> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

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

<ParamField path="id" type="string" required>
  The validation ID returned when you created the KYC validation
</ParamField>

### Headers

```json theme={null}
{
  "Authorization": "Bearer YOUR_API_KEY"
}
```

## Response

### Success Response (200 OK)

```json theme={null}
{
  "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

<ResponseField name="providerSessionUrl" type="string">
  **The verification URL to share with your customer**. This is the main field you need.
</ResponseField>

<ResponseField name="status" type="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
</ResponseField>

<ResponseField name="decision" type="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
</ResponseField>

<ResponseField name="documentsVerified" type="array">
  List of documents that were verified (after completion)
</ResponseField>

<ResponseField name="biometricResult" type="object">
  Results of biometric verification (after completion)
</ResponseField>

<ResponseField name="riskAssessment" type="object">
  Risk assessment information (after completion)
</ResponseField>

<ResponseField name="verifiedFields" type="array">
  List of fields successfully verified (e.g., \["firstName", "lastName", "dateOfBirth"])
</ResponseField>

<ResponseField name="extractedData" type="object">
  Personal data extracted from the document
</ResponseField>

<ResponseField name="verifiedAt" type="string">
  Timestamp when verification was completed
</ResponseField>

## Example Request

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  ```

  ```python Python theme={null}
  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 cURL theme={null}
  curl -X GET https://api.gu1.ai/api/kyc/validations/550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

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

<CodeGroup>
  ```javascript Node.js theme={null}
  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;
  ```

  ```python Python theme={null}
  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']
  ```
</CodeGroup>

## Sharing the URL with Customers

Once you have the verification URL, you can share it with your customer through various channels:

### Email Example

```html theme={null}
<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

```javascript theme={null}
// 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)

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Handle Expired Sessions">
    Verification URLs typically expire after 7 days. If a customer's session expires, create a new validation.
  </Accordion>

  <Accordion title="Monitor Status Changes">
    Use webhooks to receive real-time notifications when the verification status changes, rather than polling this endpoint.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Webhook Integration" icon="webhook" href="/en/use-cases/kyc/webhook-integration">
    Receive real-time status updates
  </Card>

  <Card title="Check Verification Status" icon="magnifying-glass" href="/en/use-cases/kyc/check-status">
    Query validation results
  </Card>
</CardGroup>