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>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "integrationCode": "<string>"
}
'
{
  "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 using a configured integration provider. After creating the validation, you’ll receive a verification URL that you can share with your customer to complete identity verification.

​
Complete Flow Diagram

Understanding the full sequence from entity creation to KYC validation:
1. Entity ID from POST /entities
  • Yes, entityId comes from creating a person entity first via POST /api/entities
  • You cannot create a KYC validation without an existing entity
  • Store the entityId after entity creation to use in KYC validation request
2. Integration Code
  • global_gueno_validation_kyc is the standard code for full KYC verification
  • This code must match an integration configured for your organization
  • In sandbox, this code works out-of-the-box with no setup
3. Verification URL
  • The providerSessionUrl in the response is what you send to your user
  • This URL is typically valid for 30 days (check expiresAt field)
  • Users complete the entire verification flow on the provider’s hosted page
4. Webhook vs Polling
  • Webhooks provide instant notification when verification completes
  • You can also poll GET /api/kyc/validations/:id for status updates
  • Best practice: Use webhooks + polling as fallback

​
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 a KYC integration provider activated (e.g., global_gueno_validation_kyc)
  3. Valid API key: Authenticate with your API key
Sandbox vs Production: Sandbox environments do NOT require profile setup or pre-configuration. You can test KYC validations immediately in sandbox with test data. Production environments require:
  • Completed organization onboarding
  • KYC integration provider activated by gu1 team
  • Sufficient credit balance for KYC operations
To get started in sandbox, simply use your sandbox API key - no additional setup needed.

​
Important Behaviors

​
Duplicate Entity Handling

What happens if you call POST /entities multiple times with the same taxId?The API will create duplicate entities with different UUIDs. This is by design to support use cases like:
  • Historical record keeping
  • Multiple verification attempts
  • Different entity contexts (e.g., same person in different roles)
Best Practice to Avoid Duplicates:
  1. Check if entity exists first: Use GET /api/entities?taxId=12345678 before creating
  2. Store entityId in your database: Map your user ID to the gu1 entityId
  3. Use existing entityId: Reuse the same entity for multiple KYC validations
Example - Check before create:
// Check if entity exists
const existing = await fetch('https://api.gu1.ai/api/entities?taxId=12345678', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});

let entityId;
if (existing.data && existing.data.length > 0) {
  entityId = existing.data[0].id; // Use existing entity
} else {
  // Create new entity
  const newEntity = await fetch('https://api.gu1.ai/api/entities', {
    method: 'POST',
    headers: { 'Authorization': 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json' },
    body: JSON.stringify({ type: 'person', taxId: '12345678', name: 'John Doe' })
  });
  entityId = newEntity.data.id;
}

// Now create KYC validation with the entityId

​
Multiple KYC Validations per Entity

You can create multiple KYC validations for the same entity:
  • Each validation gets a unique ID and session
  • Only the most recent approved validation is marked as isCurrent: true
  • Use cases: Re-verification, expired validations, failed attempts

​
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 verifyType: string (uuid)
​
integrationCode
string
required
The integration provider code for KYC validationStandard Value: global_gueno_validation_kyc (recommended for most use cases)Type: string (min length: 1)
What is integrationCode?The integrationCode identifies which KYC provider integration to use for verification. Think of it as selecting the verification service.Available Integration Codes:
  • global_gueno_validation_kyc - Recommended - Full KYC with document + selfie + face match + liveness
  • Custom codes may be configured for your organization (contact support)
How to find your integration code:
  1. Log in to gu1 Dashboard
  2. Navigate to Settings → Integrations → KYC Providers
  3. Your active integration code will be listed there
In sandbox environments, global_gueno_validation_kyc works immediately with no configuration.

​
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',
    integrationCode: 'global_gueno_validation_kyc'
  })
});

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