Skip to main content

​
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:
  1. Authenticate with the API
  2. Define a custom schema for your company data
  3. Create a company entity
  4. Apply risk rules (via dashboard)
  5. 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:
1

Log in to Dashboard

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

Navigate to API Keys

Click on Settings → API Keys in the sidebar
3

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"
        }
      ]
    }
  }'

{
  "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
    }
  }'

{
  "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"
  }'

{
  "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)

Rule configuration is done through the gu1 dashboard for security and ease of use.
  1. Go to your gu1 Dashboard
  2. Navigate to Risk Analysis → Entities
  3. Find “Acme Corporation” and click to view details
  4. Go to the Rules tab and click Apply Rules
  5. 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

Data Mapping

Deep dive into smart data mapping and transformations

API Reference

Explore all available API endpoints

Webhook Events

Complete list of webhook events and payloads

​
Need Help?