Skip to main content
POST
http://api.gu1.ai
/
api
/
kyc
/
validations
Create KYC Validation
curl --request POST \
  --url http://api.gu1.ai/api/kyc/validations \
  --header 'Authorization: Bearer <token>'
{
  "id": "<string>",
  "entityId": "<string>",
  "organizationId": "<string>",
  "sessionId": "<string>",
  "status": "<string>",
  "provider": "<string>",
  "providerSessionUrl": "<string>",
  "isCurrent": true,
  "metadata": {},
  "createdAt": "<string>",
  "updatedAt": "<string>"
}

​
Overview

This endpoint creates a new KYC validation session for a person entity. After creating the validation, you’ll receive a verification URL that you can share with your customer.

​
Prerequisites

Before creating a KYC validation:
  1. Person entity must exist: Create a person entity using the Entities API
  2. KYC integration configured: Your organization must have the KYC integration enabled
  3. Valid API key: Authenticate with your API key

​
Request

​
Endpoint

POST https://api.gu1.ai/api/kyc/validations

​
Headers

{
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json"
}

​
Body Parameters

​
entityId
string
required
The UUID of the person entity to verify
​
workflowId
string
Custom workflow ID for verification (optional, uses default if not provided)
​
webhookUrl
string
Custom webhook URL for this validation (optional, uses organization default)
​
metadata
object
Custom metadata to attach to this validation (max 10KB)

​
Response

​
Success Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entityId": "123e4567-e89b-12d3-a456-426614174000",
  "organizationId": "org_abc123",
  "sessionId": "session_xyz789",
  "status": "pending",
  "provider": "kyc_provider",
  "providerSessionUrl": "https://verify.example.com/session_xyz789",
  "isCurrent": true,
  "metadata": {
    "customField": "customValue"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

​
Response Fields

​
id
string
Unique identifier for this KYC validation
​
entityId
string
The person entity being verified
​
organizationId
string
Your organization ID
​
sessionId
string
Identity verification session identifier
​
status
string
Current status: pending, in_progress, approved, rejected, expired, abandoned
​
provider
string
KYC provider name
​
providerSessionUrl
string
The verification URL to share with your customer
​
isCurrent
boolean
Whether this is the current active validation for the entity
​
metadata
object
Custom metadata you provided
​
createdAt
string
Timestamp when validation was created
​
updatedAt
string
Timestamp of last update

​
Example Request

const response = await fetch('https://api.gu1.ai/api/kyc/validations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    entityId: '123e4567-e89b-12d3-a456-426614174000',
    metadata: {
      userId: 'user_12345',
      source: 'mobile_app'
    }
  })
});

const validation = await response.json();
console.log('Verification URL:', validation.providerSessionUrl);

​
Error Responses

​
Entity Not Found (404)

{
  "error": "ENTITY_NOT_FOUND",
  "message": "Entity not found"
}

​
Invalid Entity Type (400)

{
  "error": "INVALID_ENTITY_TYPE",
  "message": "KYC validation is only available for person entities"
}

​
KYC Not Configured (400)

{
  "error": "KYC_NOT_CONFIGURED",
  "message": "KYC integration is not configured for this organization. Please contact your administrator."
}

​
Next Steps

After creating a validation:
  1. Extract the verification URL from providerSessionUrl
  2. Share the URL with your customer via email, SMS, or in-app
  3. Set up webhook endpoint to receive completion notifications
  4. Monitor validation status using the validation ID

Get KYC URL

Learn how to retrieve the URL

Webhook Integration

Configure webhook notifications