Create KYC Validation

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

Full sequence from entity creation to KYC validation (production flow; in sandbox with test document numbers the provider step is skipped and the API returns the mock result and webhooks immediately—see Sandbox mock data):

Key Points in the Flow

1. Entity and duplicate taxId

Create the person entity first via POST /api/entities (with countryCode). If the taxId already exists in the organization, the API returns 409 and does not create a duplicate; use the existing entity’s ID.
You need an existing entityId to create a KYC validation.

2. Integration code

global_gueno_validation_kyc is the standard code for full KYC verification and works in sandbox with no extra setup.

3. Verification URL

In production, the response includes providerSessionUrl. Send that URL to your user; they complete the flow on the provider’s hosted page (document + selfie). The URL is valid until expiresAt.
In sandbox, if the entity’s document number is in the test list, no provider session is used: the API returns 201 with pending status and moments later updates the validation and sends webhooks (e.g. kyc.validation_approved or kyc.validation_rejected) with no user step. Important: You must have a webhook endpoint configured to receive the responses - see Sandbox mock data.

4. Webhook events

When the validation finishes, the API sends a webhook to your URL. The event is one of: kyc.validation_approved, kyc.validation_rejected, kyc.validation_abandoned, kyc.validation_expired, kyc.validation_cancelled (not a single “completed” event). The payload is the full validation object.
You can also poll GET /api/kyc/validations/:id for status updates.

Prerequisites

Before creating a KYC validation:

Person entity must exist: Create a person entity using the Entities API
KYC integration configured: Your organization must have a KYC integration provider activated (e.g., global_gueno_validation_kyc)
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.

Mock data (sandbox)

In sandbox, when the person entity’s document number (taxId) matches one of our test values, the API returns an immediate mock result (e.g. approved, rejected, cancelled) and sends the corresponding webhooks—no real verification is run. Document format does not matter (e.g. 99.990.001 and 99990001 both work). For the full list of test document numbers by format (Argentina DNI/CUIT, Brazil CPF/CNPJ), expected outcomes, and example responses, see Sandbox mock data.

Important Behaviors

Duplicate taxId (POST /entities)

When you call POST /api/entities with a taxId that already exists in the same organization for the same entity type (person/company), the API does not create a second entity. It returns 409 Conflict with error code DUPLICATE_TAX_ID and includes the existing entity’s id, name, and type in the response details.What you should do:

Option A – Check first: Use GET /api/entities?taxId=12345678 (or the by-tax-id endpoint) before creating. If an entity exists, use its entityId for KYC.
Option B – Handle 409: If you get 409, read error.details.existingEntityId from the response and use that entityId for your KYC validation.
Reuse the same entity: Use one entity per person/company and create multiple KYC validations on that same entityId if you need re-verification or new attempts.

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' }
});
const data = await existing.json();

let entityId;
if (data.data && data.data.length > 0) {
  entityId = data.data[0].id; // Use existing entity
} else {
  const createRes = 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', countryCode: 'AR' })
  });
  const created = await createRes.json();
  entityId = created.entity?.id ?? created.data?.id;
}

// 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"
}

Query Parameters (optional)

doubleCheckRenaper

boolean

When true, enables RENAPER double-check for Argentina entities. After the KYC provider approves, the API validates the document against the official Argentine registry (RENAPER). If the check fails, the validation is set to rejected and the reason is stored as a code in metadata.warnings and in metadata.responseDoubleChecks.renaper.errorCode.Type: boolean (e.g. ?doubleCheckRenaper=true)Requirements: Entity must be from Argentina (countryCode === 'AR'), and the organization must have RENAPER credentials configured in System Settings → Organizations → Config. If credentials are missing, the creation may fail or the double-check will be skipped depending on configuration.

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:

Log in to gu1 Dashboard
Navigate to Settings → Integrations → KYC Providers
Your active integration code will be listed there

In sandbox environments, global_gueno_validation_kyc works immediately with no configuration.

doubleCheckRenaper

boolean

Same as query param doubleCheckRenaper. When true, enables RENAPER double-check for Argentina. Can be sent in the body or as ?doubleCheckRenaper=true. If both are present, the query param takes precedence.

omitWarnings

string[]

Optional list of KYC warning risk codes (exact strings). Stored on the validation as metadata.omitWarnings. After the session completes, if the validation would be in_review, warnings is non-empty, and every code in warnings appears in this list, the API sets status to approved and keeps all warnings for display and audit. If any warning is not in omitWarnings, status stays in_review. If warnings is empty while status is in_review, this rule does not auto-approve. Invalid or unknown codes in the request body return 400. When the rule applies, metadata.kycOmitWarningsApplied records the decision timestamp and matched warnings.Type: string[] (each element must be an allowlisted code; duplicates are ignored)

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",
    "doubleChecks": { "renaper": true }
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z"
}

When RENAPER double-check is enabled, metadata.doubleChecks.renaper is set to true at creation. After the KYC provider approves and the double-check runs, metadata.responseDoubleChecks.renaper is populated (see RENAPER double-check below).

Response Fields

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 validation status. Possible values:

pending - Validation created, waiting for customer to start
in_progress - Customer is completing verification (filling out form)
in_review - Verification completed, requires manual review from compliance team
approved - Verification successful
rejected - Verification failed
expired - Verification session expired (e.g. after 7 days)
abandoned - Customer started but didn’t complete
cancelled - Validation manually cancelled

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. When RENAPER double-check is requested, includes doubleChecks: { renaper: true }. After approval and double-check execution, may include responseDoubleChecks.renaper (see RENAPER double-check section).

createdAt

string

Timestamp when validation was created

updatedAt

string

Timestamp of last update

After approval, media keys appear inside decision. To download files (images, video), use GET /api/kyc/validations/:id/media?key=... with Authorization: Bearer. Full details: Get KYC validation media.

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."
}

RENAPER double-check (Argentina)

When doubleCheckRenaper is true and the entity is from Argentina, after the KYC provider approves the validation, the API runs a cross-check against the official Argentine registry (RENAPER). If this check fails, the validation is set to rejected and the reason is stored in metadata.

How to send it

Body: { "entityId": "...", "integrationCode": "...", "doubleCheckRenaper": true }
Query: POST /api/kyc/validations?doubleCheckRenaper=true with the same body (without the field). Query param overrides body if both are present.

When it runs

Validation is created with metadata.doubleChecks.renaper: true.
User completes verification; KYC provider approves.
API then calls RENAPER with DNI + gender from the verification.
API compares: (1) document number from registry vs KYC document number; (2) transaction number (personal_number from KYC) vs id_tramite_principal from RENAPER.
If both match → validation stays approved. If not → validation is set to rejected and the failure reason is stored.

Where the result is stored

All RENAPER double-check results are stored in metadata.responseDoubleChecks.renaper (and when the check fails, a code is also added to metadata.warnings for display). Shape of metadata.responseDoubleChecks.renaper:

Field	Type	Description
`verified`	boolean	`true` if the double-check passed.
`matchResult`	string	`"match"` \| `"mismatch"` \| `"error"`.
`verifiedAt`	string	ISO timestamp when the check was run.
`personalNumber`	string	Transaction number from KYC (normalized).
`idTramitePrincipal`	string	Transaction number from RENAPER.
`renaperData`	object	Raw RENAPER API response (for debugging).
`errorCode`	string	Present when failed; see error codes below.
`error`	string	Optional legacy message; prefer using `errorCode` and translating in your UI.

Error codes (when RENAPER fails)

When the double-check fails, metadata.warnings contains one of the following codes (and metadata.responseDoubleChecks.renaper.errorCode is set to the same value). Your UI should translate these codes into user-facing messages.

Code	Meaning
`RENAPER_DNI_MISSING`	No document number (DNI) was obtained from the KYC verification.
`RENAPER_GENDER_MISSING`	Gender (M/F) is required to call RENAPER and was not available.
`RENAPER_VERIFICATION_UNAVAILABLE`	Could not complete the cross-check with the registry (e.g. network/API error). Retry later.
`RENAPER_DNI_NOT_MATCH`	The document number from the verification does not match the official registry.
`RENAPER_TRAMITE_DATA_MISSING`	Transaction number could not be compared (missing from KYC or RENAPER response).
`RENAPER_TRAMITE_ID_NOT_MATCH`	The document transaction number does not match the registry. Common when the person used an older copy of the ID, the document is expired, or it was reissued; they should verify again with their current, valid ID.

Why the validation is rejected

If the RENAPER double-check fails, the validation status is set to rejected. The reason is not a free-text message in the API response; it is the code in metadata.warnings and metadata.responseDoubleChecks.renaper.errorCode. Use the table above to map codes to your own copy or use the translation keys in the dashboard (e.g. kyc.rejectionReasonCodes.*).

Next Steps

After creating a validation:

Extract the verification URL from providerSessionUrl
Share the URL with your customer via email, SMS, or in-app
Set up webhook endpoint to receive completion notifications
Monitor validation status using the validation ID
After approval, read media keys from decision and download files — see Get KYC validation media

Get KYC URL

Learn how to retrieve the URL

Webhook Integration

Configure webhook notifications

Getting Started

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

Documentation Index

​Overview

​Complete Flow Diagram

​Prerequisites

​Mock data (sandbox)

​Important Behaviors

​Duplicate taxId (POST /entities)

​Multiple KYC Validations per Entity

​Request

​Endpoint

​Headers

​Query Parameters (optional)

​Body Parameters

​Response

​Success Response (201 Created)

​Response Fields

​Example Request

​Error Responses

​Entity Not Found (404)

​Invalid Entity Type (400)

​KYC Not Configured (400)

​RENAPER double-check (Argentina)

​How to send it

​When it runs

​Where the result is stored

​Error codes (when RENAPER fails)

​Why the validation is rejected

​Next Steps

Get KYC URL

Webhook Integration

Overview

Complete Flow Diagram

Prerequisites

Mock data (sandbox)

Important Behaviors

Duplicate taxId (POST /entities)

Multiple KYC Validations per Entity

Request

Endpoint

Headers

Query Parameters (optional)

Body Parameters

Response

Success Response (201 Created)

Response Fields

Example Request

Error Responses

Entity Not Found (404)

Invalid Entity Type (400)

KYC Not Configured (400)

RENAPER double-check (Argentina)

How to send it

When it runs

Where the result is stored

Error codes (when RENAPER fails)

Why the validation is rejected

Next Steps