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:
Navigate to API Keys
Click on 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" } ] } }'
{ "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.
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 Need Help? 
