Entities Overview

What are Entities?

Entities are the core objects in gu1 that represent the subjects of your risk analysis. An entity can be a company, an individual, a transaction, or any custom type relevant to your business. Each entity contains:

Identity information (name, external ID, type)
Risk assessment (risk score, status)
Custom data (flexible JSON for your specific fields)
Relationships (connections to other entities)
Analysis results (AI-powered insights)
Timeline (history of changes and events)

Entity Types

Company

Corporate entities for KYB analysis

Person

Individual entities for KYC analysis

Transaction

Financial transactions for monitoring

Custom

Any custom entity type for your business

Entity Lifecycle

Creation

Entity is created via API with basic information and optional custom data

Enrichment

Additional data is added through updates or integrations

Analysis

AI-powered risk analysis is automatically generated

Rule Evaluation

Risk rules are applied to calculate risk score and generate alerts

Investigation

Alerts trigger investigations for manual review

Resolution

Entity status is updated based on investigation outcomes

Entity Status

Entities can have different statuses throughout their lifecycle:

Status	Description	Use Case
active	Entity is active and being monitored	Normal operation
inactive	Entity is no longer active	Closed accounts
under_review	Entity is being investigated	Alert triggered
approved	Entity passed all checks	Low risk
rejected	Entity failed compliance checks	High risk
suspended	Entity temporarily suspended	Pending information

Risk Scoring

Every entity has a risk score (0-100) calculated based on:

AI Analysis

Machine learning models analyze entity behavior, patterns, and anomalies

Rule-Based Scoring

Custom rules evaluate specific conditions and assign risk points

Compliance Checks

Sanctions lists, PEPs, adverse media screening results

Historical Behavior

Transaction patterns, account activity, and changes over time

Relationship Analysis

Connected entities and their risk profiles

Risk Score Ranges:

0-25: Low risk (green)
26-50: Medium risk (yellow)
51-75: High risk (orange)
76-100: Critical risk (red)

Entity Data Structure

{
  "id": "a7c4c07f-a1f5-49d6-8c17-1577d0787a2e",
  "type": "company",
  "name": "Acme Corporation",
  "externalId": "TAX123456789",
  "country": "US",
  "riskScore": 35,
  "status": "active",
  "entityData": {
    "industry": "Technology",
    "annual_revenue": 5000000,
    "employees": 50,
    "incorporation_date": "2010-01-15",
    "beneficial_owners": [
      {
        "name": "John Doe",
        "ownership": 60,
        "isPEP": false
      }
    ],
    "compliance": {
      "kyb_completed": true,
      "sanctions_checked": true,
      "adverse_media_found": false
    }
  },
  "organizationId": "org_abc123",
  "createdAt": "2025-10-03T12:00:00Z",
  "updatedAt": "2025-10-03T14:30:00Z"
}

Core Fields

Field	Type	Required	Description
`type`	string	Yes	Entity type (company, person, transaction, custom)
`name`	string	Yes	Entity name
`externalId`	string	No	Your unique identifier for this entity
`country`	string	No	ISO country code (e.g., “US”, “UK”)
`entityData`	object	No	Flexible JSON for custom fields
`riskScore`	number	No	Risk score 0-100 (auto-calculated)
`status`	enum	No	Entity status (default: “active”)

Custom Entity Data

The entityData field is a flexible JSON object where you can store any custom fields relevant to your use case: KYB Example:

{
  "entityData": {
    "tax_id": "12-3456789",
    "industry": "Financial Services",
    "annual_revenue": 10000000,
    "employees": 150,
    "incorporation_date": "2015-03-20",
    "website": "https://example.com",
    "beneficial_owners": [...],
    "licenses": [...]
  }
}

KYC Example:

{
  "entityData": {
    "date_of_birth": "1985-06-15",
    "nationality": "US",
    "occupation": "Software Engineer",
    "annual_income": 120000,
    "identity_verified": true,
    "pep_status": false,
    "documents": [...]
  }
}

Transaction Example:

{
  "entityData": {
    "amount": 50000,
    "currency": "USD",
    "sender_account": "ACC123",
    "receiver_account": "ACC456",
    "transaction_type": "wire_transfer",
    "purpose": "Business payment",
    "timestamp": "2025-10-03T10:30:00Z"
  }
}

Common Operations

Create Entity

POST /entities - Create new entity

Get Entity

GET /entities/:id - Retrieve entity details

List Entities

GET /entities - Query entities with filters

Update Entity

PUT /entities/:id - Update entity data

Delete Entity

DELETE /entities/:id - Remove entity

Bulk Import

POST /entities/bulk - Import multiple entities

Best Practices

Use External IDs

Always set externalId to your internal identifier for easy reconciliation and updates

Consistent Entity Types

Use consistent entity type values across your organization (e.g., “company” vs “corporate”)

Set Country Codes

Always include ISO country codes for proper risk assessment and compliance checks

Structure Entity Data

Organize entityData with consistent field names and nested objects for complex data

Track Updates

Use the updatedAt timestamp to detect changes and sync with your systems

Bulk Operations

Use bulk import for creating multiple entities (>10) to improve performance

Advanced Features

AI-Powered Analysis

Every entity can have AI-generated risk analysis:

POST /ai-analysis/entity/:entityId

Returns comprehensive analysis including:

Executive summary
Behavioral patterns
Risk factors identified
Recommendations
Confidence score

Learn more →

Entity Relationships

Connect entities to show ownership, transactions, or other relationships:

{
  "sourceEntityId": "entity_1",
  "targetEntityId": "entity_2",
  "relationshipType": "owns",
  "strength": 0.85
}

Document Attachments

Attach documents (ID cards, licenses, contracts) to entities:

POST /documents/entity/:entityId/upload

Learn more →

Example Workflows

KYB Onboarding

Complete company onboarding workflow

KYC Verification

Individual customer verification process

Transaction Monitoring

Real-time transaction screening

Ongoing Monitoring

Continuous entity monitoring setup

Next Steps

Create Your First Entity

Follow the Create Entity guide to add an entity

Setup Data Mapping

Use Custom Schemas for structured imports

Configure Rules

Apply risk rules through the dashboard to calculate risk scores

Monitor & Act

Setup webhooks to receive alerts when risk scores change

Getting Started

API Reference

Data Ingestion

Entities

Documents

Know Your Business (KYB)

Know Your Customer (KYC)

Transaction Monitoring

Interactive Tutorials

Entities Overview

What are Entities?

Entity Types

Company

Person

Transaction

Custom

Entity Lifecycle

Entity Status

Risk Scoring

Entity Data Structure

Core Fields

Custom Entity Data

Common Operations

Create Entity

Get Entity

List Entities

Update Entity

Delete Entity

Bulk Import

Best Practices

Advanced Features

AI-Powered Analysis

Entity Relationships

Document Attachments

Example Workflows

KYB Onboarding

KYC Verification

Transaction Monitoring

Ongoing Monitoring

Next Steps

Getting Started

API Reference

Data Ingestion

Entities

Documents

Know Your Business (KYB)

Know Your Customer (KYC)

Transaction Monitoring

Interactive Tutorials

​What are Entities?

​Entity Types

Company

Person

Transaction

Custom

​Entity Lifecycle

​Entity Status

​Risk Scoring

​Entity Data Structure

​Core Fields

​Custom Entity Data

​Common Operations

Create Entity

Get Entity

List Entities

Update Entity

Delete Entity

Bulk Import

​Best Practices

​Advanced Features

​AI-Powered Analysis

​Entity Relationships

​Document Attachments

​Example Workflows

KYB Onboarding

KYC Verification

Transaction Monitoring

Ongoing Monitoring

​Next Steps

What are Entities?

Entity Types

Entity Lifecycle

Entity Status

Risk Scoring

Entity Data Structure

Core Fields

Custom Entity Data

Common Operations

Best Practices

Advanced Features

AI-Powered Analysis

Entity Relationships

Document Attachments

Example Workflows

Next Steps