Quickstart: KYB Risk Analysis in 5 Minutes

Overview

This quickstart guide will walk you through creating your first Know Your Business (KYB) risk analysis using gu1’s API. You’ll learn how to:

Authenticate with the API
Define a custom schema for your company data
Create a company entity
Apply risk rules (via dashboard)
Monitor alerts and investigations

Prerequisites: You’ll need a gu1 account and an API key. Sign up at app.gu1.ai if you haven’t already.

Step 1: Get Your API Key

First, obtain your API key from the gu1 dashboard:

Go to app.gu1.ai and log in to your account

Navigate to API Keys

Click Settings → API Keys in the sidebar

Create New Key

Click Create API Key, give it a name (e.g., “KYB Integration”), and copy the key

Keep your API key secure! Never commit it to version control or share it publicly.

Step 2: Define Your Company Schema

Tell gu1 what data fields you’ll be sending for companies:

curl -X POST http://api.gu1.ai/custom-schemas \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "description": "Company information for KYB analysis",
    "type": "database",
    "category": "financial",
    "schemaData": {
      "fields": [
        {
          "name": "company_name",
          "type": "string",
          "required": true,
          "description": "Legal company name"
        },
        {
          "name": "tax_id",
          "type": "string",
          "required": true,
          "description": "Tax identification number"
        },
        {
          "name": "country",
          "type": "string",
          "required": true,
          "description": "Country of incorporation"
        },
        {
          "name": "industry",
          "type": "string",
          "required": false,
          "description": "Industry sector"
        },
        {
          "name": "annual_revenue",
          "type": "number",
          "required": false,
          "description": "Annual revenue in USD"
        }
      ]
    }
  }'

Response

{
  "success": true,
  "schema": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Corporate KYB Data",
    "version": "1.0.0",
    "organizationId": "your-org-id",
    "createdAt": "2025-10-03T12:00:00Z"
  }
}

Step 3: Map Fields to gu1’s Model

Create a mapping configuration to tell gu1 how your fields map to its unified entity model:

curl -X POST http://api.gu1.ai/custom-schemas/mappings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "KYB Field Mapping",
    "sourceSchemaId": "550e8400-e29b-41d4-a716-446655440000",
    "targetSchemaType": "gueno_entity",
    "mappingData": {
      "mappings": [
        {
          "id": "1",
          "sourceField": "company_name",
          "targetField": "name",
          "transformation": { "type": "direct" },
          "required": true,
          "dataType": "string"
        },
        {
          "id": "2",
          "sourceField": "tax_id",
          "targetField": "external_id",
          "transformation": { "type": "direct" },
          "required": true,
          "dataType": "string"
        },
        {
          "id": "3",
          "sourceField": "country",
          "targetField": "country",
          "transformation": { "type": "direct" },
          "required": true,
          "dataType": "string"
        }
      ]
    }
  }'

Step 4: Create a Company Entity

Now you can create a company entity using the mapped schema:

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "name": "Acme Corporation",
    "externalId": "TAX123456789",
    "country": "US",
    "entityData": {
      "industry": "Technology",
      "annual_revenue": 5000000,
      "incorporation_date": "2010-01-15",
      "employees": 50
    }
  }'

Response

{
  "success": true,
  "entity": {
    "id": "a7c4c07f-a1f5-49d6-8c17-1577d0787a2e",
    "type": "company",
    "name": "Acme Corporation",
    "externalId": "TAX123456789",
    "country": "US",
    "riskScore": 0,
    "status": "active",
    "createdAt": "2025-10-03T12:05:00Z"
  }
}

Step 5: View AI Analysis

gu1 automatically generates an AI-powered risk analysis for the entity. Fetch it:

curl -X POST http://api.gu1.ai/ai-analysis/entity/a7c4c07f-a1f5-49d6-8c17-1577d0787a2e \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "language": "en"
  }'

Response

{
  "success": true,
  "analysis": {
    "executive_summary": "Acme Corporation is a US-based technology company with moderate risk profile. The company shows stable operations with consistent revenue...",
    "behavioral_analysis": "Entity demonstrates normal business patterns with no red flags in transaction history...",
    "risk_factors": [
      "Limited public information available",
      "Operating in high-risk technology sector"
    ],
    "recommendations": [
      "Request additional documentation for beneficial owners",
      "Monitor for any changes in company structure"
    ],
    "confidence_score": 0.85,
    "generated_at": "2025-10-03T12:05:30Z"
  },
  "cached": false
}

Step 6: Apply Rules (Dashboard)

You configure rules through the gu1 dashboard for security and ease of use.

Go to your gu1 Dashboard
Navigate to Risk Analysis → Entities
Find “Acme Corporation” and click to view details
Go to the Rules tab and click Apply Rules
Select pre-built KYB rules or create custom ones

Rules will automatically generate alerts and investigations based on risk thresholds.

Step 7: Monitor with Webhooks

Set up webhooks to receive real-time notifications when alerts or investigations are created:

curl -X POST http://api.gu1.ai/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/gueno",
    "events": [
      "investigation.created",
      "investigation.updated",
      "alert.created",
      "entity.risk_score_changed"
    ],
    "active": true
  }'

Next Steps

Complete KYB Guide

Learn the full KYB workflow with advanced features

Custom Schemas

Map incoming fields to gu1’s unified model for entities and rules

API Reference

Explore all available API endpoints

Webhooks

Event types, security model, and configuration in the dashboard

Need Help?

Documentation: Browse our API Reference
Support: Email us at support@gueno.com
Dashboard: app.gu1.ai

​Overview

​Step 1: Get Your API Key

​Step 2: Define Your Company Schema

​Step 3: Map Fields to gu1’s Model

​Step 4: Create a Company Entity

​Step 5: View AI Analysis

​Step 6: Apply Rules (Dashboard)

​Step 7: Monitor with Webhooks

​Next Steps

Complete KYB Guide

Custom Schemas

API Reference

Webhooks

​Need Help?

Overview

Step 1: Get Your API Key

Step 2: Define Your Company Schema

Step 3: Map Fields to gu1’s Model

Step 4: Create a Company Entity

Step 5: View AI Analysis

Step 6: Apply Rules (Dashboard)

Step 7: Monitor with Webhooks

Next Steps

Need Help?