Complete Person (KYC) Flow

Overview

This guide covers the complete flow for person entity management, from creation through enrichment, KYC validation, and risk analysis. The flow is designed to be flexible, supporting both automatic and manual processes at each stage.

Automatic vs Manual: Which Should You Use?

Quick Answer: Use Automatic for most cases. It handles everything in one API call and is faster to integrate.

Feature	Automatic Creation	Manual Creation
API Calls Required	1 call (`POST /entities/automatic`)	2-3 calls (`POST /entities`, then `POST /entities/:id/analyze`)
Enrichment	Automatic - runs in background	Manual - you trigger it separately
Risk Analysis	Automatic - executes after enrichment	Manual - you trigger it separately
Shareholder Discovery	Optional - configure in request	Not available
Integration Complexity	Simple - one-step process	Complex - orchestrate multiple steps
Credits Deduction	Automatic	Automatic (per operation)
Use When	Standard onboarding flows	Need granular control over timing
Best For	Production apps, batch processing	Testing, debugging, custom workflows

When to use Manual Creation:

You need to collect user data incrementally over multiple steps
You want to show users a progress indicator between stages
You’re debugging and want to inspect data between operations
You have custom business logic between entity creation and risk analysis

Risk Matrix Configuration

Who Defines the Risk Matrix? You configure your risk matrix rules in the gu1 dashboard before using the API.

What is a Risk Matrix?

A Risk Matrix is a collection of rules that define how entities are scored for risk. Think of it as your compliance playbook - it determines:

Which data points to check (PEP status, sanctions, adverse media, etc.)
What risk score to assign when conditions are met
Whether to approve, reject, or flag entities for review
Custom risk labels (Low/Medium/High) based on score ranges

How to Configure Your Risk Matrix

Log in to the gu1 Dashboard: https://app.gu1.ai
Navigate to Risk Matrices: Settings → Risk Matrices
Create a New Matrix: Click “New Risk Matrix”
Configure Rules: Add rules that match your compliance requirements
- Example: “If PEP detected → add 25 points to risk score”
- Example: “If sanctions match → reject and create alert”
Set Custom Labels: Define score ranges (e.g., 0-25: Low, 26-50: Medium, 51-100: High)
Save and Copy ID: Save the matrix and copy the UUID - you’ll use this in API calls

Using Risk Matrix in API

Option 1: Specify in API request (recommended for multi-tenant setups):

{
  "riskMatrixId": "uuid-of-risk-matrix"
}

Option 2: Set organization default in the dashboard:

Navigate to Settings → Organization
Set “Default Risk Matrix for Persons”
All person entities will use this matrix unless overridden

Tutorial: Setting Up Your First Risk Matrix

For a detailed walkthrough, see our guides:

Flow Diagram

Step 1: Create Person Entity

Option A: Automatic Creation (Recommended)

Automatic creation handles enrichment, shareholder discovery, and risk analysis in a single operation. Endpoint: POST /entities/automatic Request:

{
  "entityType": "person",
  "data": {
    "taxId": "12345678",
    "name": "John Doe",
    "countryCode": "US"
  },
  "enrichmentOptions": {
    "basic": ["identity_verification", "sanctions", "pep"],
    "additional": ["adverse_media", "legal_records"],
    "createShareholders": true,  // ⚠️ Only for company entities (KYB), not persons (KYC)
    "maxShareholderDepth": 2     // ⚠️ Only for company entities (KYB), not persons (KYC)
  },
  "skipRulesExecution": false,
  "riskMatrixId": "uuid-of-risk-matrix"  // Optional - see "Risk Matrix Configuration" below
}

What happens automatically:

Basic Data Enrichment: Executes providers from basic list
Entity Creation: Maps normalized data to entity structure
Additional Enrichment: Executes providers from additional list
Shareholder Discovery: Recursively creates shareholder entities (if enabled) - ⚠️ Companies only
Risk Matrix Assignment: Assigns the provided risk matrix (or default)
Risk Analysis: Executes risk matrix rules automatically (unless skipRulesExecution: true)

Note on Shareholders (createShareholders): This feature is only applicable for company entities (KYB), not person entities (KYC).When verifying a company, you can enable createShareholders: true to automatically discover and create entities for all beneficial owners and corporate shareholders.For person entities (KYC), this field is ignored since individuals don’t have shareholders. If you’re implementing person verification (KYC), you can omit this field entirely.

Response:

{
  "entity": {
    "id": "uuid",
    "organizationId": "uuid",
    "type": "person",
    "name": "John Doe",
    "taxId": "12345678",
    "countryCode": "US",
    "riskScore": "45.00",
    "riskFactors": {
      "reasons": ["PEP match found", "Sanctions screening passed"],
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Medium Risk",
        "color": "#f59e0b"
      }
    },
    "metadata": {
      "enrichment": {
        "hasData": true,
        "executedProviders": ["world_check", "sanctions_api", "pep_database"],
        "lastExecutedAt": "2025-12-24T10:30:00Z"
      }
    }
  },
  "enrichmentResult": {
    "success": true,
    "providers": ["world_check", "sanctions_api", "pep_database"],
    "dataQuality": 85,
    "confidence": 90
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "riskScore": 45
  },
  "shareholders": [
    {
      "id": "shareholder-uuid",
      "name": "Company ABC",
      "ownershipPercentage": 25
    }
  ]
}

Option B: Manual Creation

Create a person entity with basic information only, then enrich and analyze separately. Endpoint: POST /entities Request:

{
  "type": "person",
  "name": "John Doe",
  "taxId": "12345678",
  "countryCode": "US",
  "entityData": {
    "person": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-15",
      "nationality": "US"
    }
  }
}

Response:

{
  "entity": {
    "id": "uuid",
    "organizationId": "uuid",
    "type": "person",
    "name": "John Doe",
    "taxId": "12345678",
    "countryCode": "US",
    "status": "active",
    "riskScore": null,
    "metadata": {
      "enrichment": {
        "hasData": false
      }
    }
  }
}

Step 2: Enrich and Analyze (Manual Flow)

If you created the entity manually, you need to enrich it and execute risk analysis. Endpoint: POST /entities/:entityId/analyze Request:

{
  "enrichIfNeeded": true,
  "providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media"],
  "entityType": "person"
}

Available Provider Codes for KYC

Standard Provider Codes (most commonly used):

global_gueno_validation_kyc - Recommended for full KYC - Comprehensive identity verification including document + liveness + face match
world_check - PEP and sanctions screening (Refinitiv WorldCheck)
sanctions_api - Global sanctions list screening
pep_database - Politically Exposed Persons detection
adverse_media - Negative news and media monitoring
legal_records - Court records and legal proceedings
identity_verification - Basic identity validation

How to Choose Provider Codes:

For Complete KYC Verification (document + selfie + face match):
```
"providerCodes": ["global_gueno_validation_kyc"]
```

For AML Screening Only (no document upload):

"providerCodes": ["world_check", "sanctions_api", "pep_database"]

For Enhanced Due Diligence:

"providerCodes": ["world_check", "sanctions_api", "pep_database", "adverse_media", "legal_records"]

Note: Available providers depend on your organization’s subscriptions. Contact support if you need access to specific providers.

What happens:

Optional Enrichment: If enrichIfNeeded: true or providerCodes provided, runs enrichment first
Risk Analysis: Executes risk matrix rules on the entity
Score Update: Updates entity risk score and status

Response:

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "uuid",
    "entityType": "person",
    "riskScore": 45,
    "overallConfidence": 0.9,
    "totalRules": 10,
    "successfulRules": 3,
    "flags": [
      {
        "type": "PEP",
        "severity": "warning",
        "reason": "Person identified as Politically Exposed Person",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Medium Risk",
        "minScore": 25,
        "maxScore": 50,
        "color": "#f59e0b"
      }
    }
  },
  "rulesTriggered": 3,
  "executionTimeMs": 1250
}

Step 3: Enrichment Process (Deep Dive)

How Enrichment Works

The EnrichmentOrchestrator service handles all enrichment operations:

Provider Selection:
- If providerCodes specified: uses those specific providers
- Otherwise: auto-selects based on organization subscriptions and entity type
Balance Validation:
- Calculates total cost of all selected providers
- Checks organization’s credit balance
- Throws InsufficientBalanceError if balance too low
Parallel Execution:
- ALL providers execute concurrently (up to 15 simultaneous)
- Each provider has individual timeout (default: 7.5s, judicial: 15s)
- Failures in one provider don’t affect others
- Total execution time = slowest provider
Data Normalization:
- Raw provider data normalized to standard format
- Field-level conflict resolution (highest confidence, most recent, majority)
- Intelligent merging with existing enrichment data
- Quality scores calculated from all provider results
Data Storage:
- normalized_enrichment table: normalized/mapped data
- enrichment_data_current table: current enrichment snapshot
- audit_enrichment table: individual provider execution audit
- entities.metadata.enrichment: execution metadata cache
Credit Deduction:
- Balance deducted only AFTER successful execution
- Costs: varies by provider (e.g., WorldCheck: $0.50, Sanctions:$ 0.25)

How Credit Management Works

Important: Credits are deducted from your organization’s balance when enrichment providers are executed successfully.

Credit Deduction Flow:

Pre-validation: Before enrichment starts, the system checks if you have sufficient balance
Execution: Providers run in parallel (you’re only charged for successful executions)
Deduction: Credits are deducted AFTER successful completion (not upfront)
Failed providers: No charge if a provider fails or times out

Typical Costs (varies by subscription plan):

global_gueno_validation_kyc: $2.00 per verification
world_check: $0.50 per check
sanctions_api: $0.25 per screening
pep_database: $0.25 per check
adverse_media: $0.30 per search
legal_records: $0.40 per search

Check Your Balance:

GET /api/billing/balance

Monitor Credit Usage:

GET /api/billing/transactions

Add Credits:

Navigate to Dashboard → Billing → Credits
Purchase credit packages or set up auto-reload

Insufficient Balance Error:

{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}

Solution: Add credits to your account before running enrichment operations. For detailed pricing and credit management, see: Billing & Credits

Enrichment Result Structure

{
  "success": true,
  "entityId": "uuid",
  "normalized": {
    "entityType": "person",
    "normalized": {
      "fullName": "John Doe",
      "dateOfBirth": "1980-01-15",
      "nationality": "US",
      "isPep": true,
      "sanctionsMatch": false,
      "adverseMedia": [
        {
          "title": "Business Investigation",
          "date": "2023-05-10",
          "source": "Financial Times"
        }
      ]
    },
    "providers": ["world_check", "sanctions_api", "adverse_media"],
    "dataQuality": 85,
    "confidence": 90,
    "completeness": 78
  },
  "providers": ["world_check", "sanctions_api", "adverse_media"],
  "totalCostCents": 100,
  "executionTimeMs": 3500,
  "cacheHit": false,
  "metadata": {
    "providersAttempted": 3,
    "providersSucceeded": 3,
    "providersFailed": 0,
    "dataQuality": 85,
    "confidence": 90
  }
}

Step 4: Risk Analysis (Deep Dive)

How Risk Analysis Works

The RulesExecutionService handles all risk analysis operations:

Strategy Selection:
- Uses entity’s assigned risk matrix
- Risk matrix defines which rules apply and evaluation strategy
Data Loading:
- Loads entity with enrichment data
- Loads entity with KYC validation (if exists)
- Prepares execution context
Coverage Validation (Person/Company only):
- Extracts all fields required by rule conditions
- Validates that executed providers cover all required enrichment fields
- Validates that KYC validation exists if KYC fields required
- Returns error with missing fields and recommended providers if incomplete
Rules Execution:
- Filters rules by trigger event (e.g., “enrichment_completed”, “manual_evaluation”)
- Executes rules in parallel using UniversalRulesEngine
- Each rule evaluates conditions and executes actions if matched
Score Calculation:
- Accumulates scores from matched rules
- Applies evaluation strategy (score_based or confidence_based)
- Normalizes score if custom labels configured
- Calculates custom label based on score range
Status Updates:
- Updates entity risk score and risk factors
- Updates entity status if rules triggered status change
- Sends ENTITY_STATUS_CHANGED notification
Audit Trail:
- Creates evaluation record
- Logs execution event
- Creates risk analysis audit with full execution details
- Logs alerts created by rule actions
Alert Consolidation:
- After 5-second delay, consolidates related alerts
- Creates or updates investigations
- Sends appropriate notifications

Risk Analysis Result Structure

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "uuid",
    "entityType": "person",
    "riskScore": 45,
    "overallConfidence": 0.9,
    "totalRules": 10,
    "successfulRules": 3,
    "failedRules": 0,
    "rulesExecuted": [
      {
        "ruleId": "rule-uuid",
        "ruleName": "PEP Detection",
        "executed": true,
        "conditionsMet": true,
        "confidence": 0.95,
        "executionTime": 50,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 25
          },
          {
            "type": "create_alert",
            "result": {
              "alertId": "alert-uuid"
            }
          }
        ]
      }
    ],
    "flags": [
      {
        "type": "PEP",
        "severity": "warning",
        "reason": "Person identified as Politically Exposed Person",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "strategyType": "score_based",
      "normalizedScore": 38,
      "originalScore": 45,
      "customLabel": {
        "name": "Medium Risk",
        "minScore": 25,
        "maxScore": 50,
        "color": "#f59e0b",
        "severity": "medium"
      },
      "displayRange": "25-50"
    }
  },
  "rulesTriggered": 3,
  "executionTimeMs": 1250,
  "auditId": "audit-uuid"
}

Step 5: KYC Validation (Optional)

If your risk matrix rules require KYC validation fields (like kyc.documentVerified, kyc.livenessCheck), you need to create a KYC validation.

Create KYC Validation

Endpoint: POST /kyc-validations Request:

{
  "entityId": "uuid",
  "provider": "persona",
  "templateId": "tmpl_ABC123",
  "requiredFields": ["government_id", "selfie"],
  "callbackUrl": "https://your-app.com/webhooks/kyc"
}

Response:

{
  "validation": {
    "id": "kyc-uuid",
    "entityId": "entity-uuid",
    "provider": "persona",
    "status": "pending",
    "validationUrl": "https://kyc-provider.com/start?token=abc123",
    "expiresAt": "2025-12-31T23:59:59Z"
  }
}

User Completes KYC

Send user to validationUrl
User completes KYC flow (uploads documents, takes selfie, etc.)
KYC provider sends webhook to your callbackUrl

Webhook: KYC Status Update

When KYC is completed, your webhook receives:

{
  "event": "kyc.completed",
  "validationId": "kyc-uuid",
  "entityId": "entity-uuid",
  "status": "approved",
  "data": {
    "documentVerified": true,
    "livenessCheck": true,
    "faceMatch": 98.5,
    "documentType": "passport",
    "documentNumber": "AB1234567",
    "verifiedAt": "2025-12-24T15:30:00Z"
  }
}

Re-run Risk Analysis After KYC

Once KYC is completed, re-run risk analysis to evaluate KYC-dependent rules: Endpoint: POST /entities/:entityId/analyze Request:

{
  "enrichIfNeeded": false,
  "entityType": "person"
}

Now rules that check kyc.* fields will evaluate properly and the entity’s final risk score will be calculated.

Step 6: Monitor and Manage

Query Entity Status

Endpoint: GET /entities/:entityId Response includes:

Current risk score (normalized and original)
Risk factors and flags
Enrichment status and providers used
KYC validation status
Last risk evaluation timestamp

View Risk Analysis History

Endpoint: GET /risk-analysis-audits?entityId=:entityId Returns:

All risk analysis executions
Rules matched in each execution
Score changes over time
Enrichment data used

View Alerts and Investigations

Endpoint: GET /investigations?entityId=:entityId Returns:

Consolidated alerts related to the entity
Investigation status and priority
Assigned analysts and resolution notes

Best Practices

Use Automatic Creation: For most cases, use POST /entities/automatic to handle enrichment and risk analysis in one operation.
Balance Management: Always ensure sufficient credits before enrichment. Monitor balance using GET /billing/balance.
Provider Selection: Use specific providerCodes when you know which data you need. Auto-selection may include unnecessary providers.
Risk Matrix Assignment: Always assign a risk matrix when creating entities. Without a risk matrix, risk analysis won’t execute for person/company entities.
KYC Timing: Initiate KYC validation early in the onboarding flow. Some rules may require KYC data.
Coverage Validation: If risk analysis fails due to incomplete coverage, check the metadata.missingFields and run the recommended providers.
Webhook Security: Always validate webhook signatures from KYC providers to prevent spoofing.
Monitoring: Set up alerts for high-risk entities and failed enrichments.

Error Handling

Common Errors

Insufficient Balance:

{
  "error": "Insufficient balance",
  "required": 100,
  "available": 50,
  "organizationId": "uuid"
}

Solution: Add credits to organization billing account. Incomplete Coverage:

{
  "success": false,
  "error": "Incomplete data coverage",
  "warnings": [
    "Field 'sanctions.matches' requires provider: world_check or sanctions_api",
    "Field 'kyc.documentVerified' requires KYC validation"
  ],
  "metadata": {
    "missingFields": [...],
    "recommendedProviders": ["world_check", "sanctions_api"]
  }
}

Solution: Run recommended providers or create KYC validation, then re-analyze. No Risk Matrix:

{
  "success": true,
  "executed": false,
  "error": "No risk matrix assigned to person entity. Please assign a Risk Matrix to enable rule execution."
}

Solution: Assign a risk matrix to the entity using PATCH /entities/:id.

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Automatic vs Manual: Which Should You Use?

​Risk Matrix Configuration

​What is a Risk Matrix?

​How to Configure Your Risk Matrix

​Using Risk Matrix in API

​Tutorial: Setting Up Your First Risk Matrix

​Flow Diagram

​Step 1: Create Person Entity

​Option A: Automatic Creation (Recommended)

​Option B: Manual Creation

​Step 2: Enrich and Analyze (Manual Flow)

​Step 3: Enrichment Process (Deep Dive)

​How Enrichment Works

​How Credit Management Works

​Enrichment Result Structure

​Step 4: Risk Analysis (Deep Dive)

​How Risk Analysis Works

​Risk Analysis Result Structure

​Step 5: KYC Validation (Optional)

​Create KYC Validation

​User Completes KYC

​Webhook: KYC Status Update

​Re-run Risk Analysis After KYC

​Step 6: Monitor and Manage

​Query Entity Status

​View Risk Analysis History

​View Alerts and Investigations

​Best Practices

​Error Handling

​Common Errors

​Next Steps

Overview

Automatic vs Manual: Which Should You Use?

Risk Matrix Configuration

What is a Risk Matrix?

How to Configure Your Risk Matrix

Using Risk Matrix in API

Tutorial: Setting Up Your First Risk Matrix

Flow Diagram

Step 1: Create Person Entity

Option A: Automatic Creation (Recommended)

Option B: Manual Creation

Step 2: Enrich and Analyze (Manual Flow)

Step 3: Enrichment Process (Deep Dive)

How Enrichment Works

How Credit Management Works

Enrichment Result Structure

Step 4: Risk Analysis (Deep Dive)

How Risk Analysis Works

Risk Analysis Result Structure

Step 5: KYC Validation (Optional)

Create KYC Validation

User Completes KYC

Webhook: KYC Status Update

Re-run Risk Analysis After KYC

Step 6: Monitor and Manage

Query Entity Status

View Risk Analysis History

View Alerts and Investigations

Best Practices

Error Handling

Common Errors

Next Steps