Complete Company (KYB) Flow

Overview

This guide covers the complete flow for company entity management (Know Your Business), from creation through enrichment, shareholder discovery, and risk analysis. The flow supports automatic shareholder creation and recursive enrichment of the entire ownership structure.

Flow Diagram

Step 1: Create Company Entity

Option A: Automatic Creation (Recommended)

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

{
  "entityType": "company",
  "data": {
    "taxId": "87654321",
    "name": "Acme Corporation",
    "countryCode": "US"
  },
  "enrichmentOptions": {
    "basic": ["company_registry", "sanctions", "adverse_media"],
    "additional": ["financial_records", "legal_filings", "esg_ratings"],
    "createShareholders": true,
    "maxShareholderDepth": 3
  },
  "skipRulesExecution": false,
  "riskMatrixId": "uuid-of-risk-matrix"
}

What happens automatically:

Basic Data Enrichment: Executes providers from basic list (company registry, sanctions, etc.)
Company Creation: Maps normalized data to company entity structure
Additional Enrichment: Executes providers from additional list
Shareholder Discovery: Extracts shareholders from enrichment data
Recursive Shareholder Creation:
- Creates person entity for individual shareholders
- Creates company entity for corporate shareholders
- Enriches each shareholder
- Continues recursively up to maxShareholderDepth
Risk Matrix Assignment: Assigns the provided risk matrix (or default)
Risk Analysis: Executes risk matrix rules automatically (unless skipRulesExecution: true)

Response:

{
  "entity": {
    "id": "company-uuid",
    "organizationId": "uuid",
    "type": "company",
    "name": "Acme Corporation",
    "taxId": "87654321",
    "countryCode": "US",
    "riskScore": "62.00",
    "riskFactors": {
      "reasons": [
        "Adverse media found",
        "Shareholder in high-risk jurisdiction"
      ],
      "normalizedScore": 55,
      "originalScore": 62,
      "customLabel": {
        "name": "High Risk",
        "color": "#ef4444"
      }
    },
    "metadata": {
      "enrichment": {
        "hasData": true,
        "executedProviders": [
          "company_registry_us",
          "sanctions_api",
          "adverse_media",
          "financial_records"
        ],
        "lastExecutedAt": "2025-12-24T10:30:00Z"
      }
    }
  },
  "enrichmentResult": {
    "success": true,
    "providers": [
      "company_registry_us",
      "sanctions_api",
      "adverse_media",
      "financial_records"
    ],
    "dataQuality": 88,
    "confidence": 92
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 5,
    "riskScore": 62
  },
  "shareholders": [
    {
      "id": "person-shareholder-uuid",
      "type": "person",
      "name": "Jane Smith",
      "ownershipPercentage": 35,
      "riskScore": "25.00",
      "enriched": true
    },
    {
      "id": "company-shareholder-uuid",
      "type": "company",
      "name": "Investment Holdings LLC",
      "ownershipPercentage": 40,
      "riskScore": "48.00",
      "enriched": true,
      "shareholders": [
        {
          "id": "nested-person-uuid",
          "type": "person",
          "name": "John Doe",
          "ownershipPercentage": 100,
          "riskScore": "15.00"
        }
      ]
    },
    {
      "id": "person-shareholder-2-uuid",
      "type": "person",
      "name": "Bob Johnson",
      "ownershipPercentage": 25,
      "riskScore": "18.00"
    }
  ]
}

Option B: Manual Creation

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

{
  "type": "company",
  "name": "Acme Corporation",
  "taxId": "87654321",
  "countryCode": "US",
  "entityData": {
    "company": {
      "legalName": "Acme Corporation Inc.",
      "registrationNumber": "REG123456",
      "incorporationDate": "2010-05-15",
      "industry": "Technology",
      "website": "https://acme-corp.example"
    }
  }
}

Response:

{
  "entity": {
    "id": "company-uuid",
    "organizationId": "uuid",
    "type": "company",
    "name": "Acme Corporation",
    "taxId": "87654321",
    "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": [
    "company_registry_us",
    "sanctions_api",
    "adverse_media",
    "financial_records",
    "beneficial_ownership"
  ],
  "entityType": "company"
}

What happens:

Enrichment: Runs specified providers to gather company data
Shareholder Discovery: Identifies shareholders from provider data (but doesn’t auto-create)
Risk Analysis: Executes risk matrix rules on the company
Score Update: Updates company risk score and status

Response:

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "company-uuid",
    "entityType": "company",
    "riskScore": 62,
    "overallConfidence": 0.92,
    "totalRules": 15,
    "successfulRules": 5,
    "flags": [
      {
        "type": "ADVERSE_MEDIA",
        "severity": "warning",
        "reason": "Company mentioned in 3 adverse media articles",
        "confidence": 0.88
      },
      {
        "type": "HIGH_RISK_JURISDICTION",
        "severity": "critical",
        "reason": "Shareholder based in high-risk jurisdiction",
        "confidence": 0.95
      }
    ],
    "strategyEvaluation": {
      "normalizedScore": 55,
      "originalScore": 62,
      "customLabel": {
        "name": "High Risk",
        "minScore": 50,
        "maxScore": 75,
        "color": "#ef4444"
      }
    }
  },
  "rulesTriggered": 5,
  "executionTimeMs": 2100
}

Step 3: Shareholder Discovery and Creation

Automatic Shareholder Creation (via /entities/automatic)

When using automatic creation with createShareholders: true, the system:

Extracts Shareholders: From enrichment provider data (e.g., company registry, beneficial ownership databases)
Creates Entities: For each shareholder (person or company)
Enriches Shareholders: Runs enrichment on each shareholder entity
Recursive Processing: For company shareholders, repeats the process up to maxShareholderDepth
Links Relationships: Creates ownership relationships in the entity graph

Example Shareholder Data Structure:

{
  "shareholders": [
    {
      "name": "Jane Smith",
      "type": "person",
      "ownershipPercentage": 35,
      "position": "CEO",
      "taxId": "11111111"
    },
    {
      "name": "Investment Holdings LLC",
      "type": "company",
      "ownershipPercentage": 40,
      "taxId": "22222222",
      "countryCode": "US"
    }
  ]
}

Manual Shareholder Creation

If you need to create shareholders manually: Step 1: Create the shareholder entity using POST /entities or POST /entities/automatic Step 2: Link the shareholder to the parent company:

POST /entity-relationships
{
  "fromEntityId": "shareholder-uuid",
  "toEntityId": "company-uuid",
  "relationshipType": "SHAREHOLDER_OF",
  "metadata": {
    "ownershipPercentage": 35,
    "position": "Board Member",
    "since": "2020-01-01"
  }
}

Step 4: Enrichment Process (Company-Specific)

Company Enrichment Providers

Common providers for company enrichment:

company_registry_us: Company registration data, officers, shareholders
company_registry_uk: UK Companies House data
company_registry_eu: European company registries
sanctions_api: Sanctions screening for companies
adverse_media: News and media mentions
financial_records: Financial statements, credit ratings
beneficial_ownership: Ultimate beneficial ownership (UBO) data
legal_filings: Court cases, legal proceedings
esg_ratings: Environmental, social, governance ratings

Enrichment Result (Company)

{
  "success": true,
  "entityId": "company-uuid",
  "normalized": {
    "entityType": "company",
    "normalized": {
      "legalName": "Acme Corporation Inc.",
      "tradingNames": ["Acme", "Acme Corp"],
      "registrationNumber": "REG123456",
      "incorporationDate": "2010-05-15",
      "status": "active",
      "industry": "Technology",
      "employees": 150,
      "revenue": 25000000,
      "directors": [
        {
          "name": "Jane Smith",
          "position": "CEO",
          "appointedDate": "2015-03-10"
        }
      ],
      "shareholders": [
        {
          "name": "Jane Smith",
          "ownershipPercentage": 35,
          "type": "person"
        },
        {
          "name": "Investment Holdings LLC",
          "ownershipPercentage": 40,
          "type": "company",
          "countryCode": "US"
        }
      ],
      "sanctionsMatch": false,
      "adverseMedia": [
        {
          "title": "Company Settles Dispute",
          "date": "2023-08-20",
          "source": "Business Journal",
          "sentiment": "negative"
        }
      ],
      "creditRating": "BBB",
      "esgScore": 72
    },
    "providers": [
      "company_registry_us",
      "sanctions_api",
      "adverse_media",
      "financial_records",
      "esg_ratings"
    ],
    "dataQuality": 88,
    "confidence": 92,
    "completeness": 85
  },
  "providers": [
    "company_registry_us",
    "sanctions_api",
    "adverse_media",
    "financial_records",
    "esg_ratings"
  ],
  "totalCostCents": 250,
  "executionTimeMs": 5200,
  "cacheHit": false
}

Step 5: Risk Analysis (Company-Specific)

Company Risk Rules Examples

Common risk rules for companies:

Sanctions Screening: Check if company or shareholders on sanctions lists
High-Risk Jurisdiction: Check if incorporated or operating in high-risk countries
Adverse Media: Count negative news articles
Financial Health: Evaluate credit rating and financial ratios
ESG Risk: Check ESG scores and controversies
Ownership Structure: Analyze shareholder risk (complex structures, offshore entities)
Legal Proceedings: Count active lawsuits and regulatory actions
PEP Connections: Check if directors/shareholders are PEPs

Risk Analysis with Shareholder Risk

The risk analysis considers:

Company Direct Risk: Based on company’s own data
Shareholder Risk: Aggregated risk from all shareholders
Ownership Complexity: Risk from complex or opaque ownership structures

Example Result:

{
  "success": true,
  "executed": true,
  "result": {
    "entityId": "company-uuid",
    "entityType": "company",
    "riskScore": 62,
    "overallConfidence": 0.92,
    "rulesExecuted": [
      {
        "ruleId": "rule-uuid-1",
        "ruleName": "Adverse Media Detection",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 20
          }
        ]
      },
      {
        "ruleId": "rule-uuid-2",
        "ruleName": "Shareholder High-Risk Jurisdiction",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 30
          },
          {
            "type": "create_alert",
            "result": {
              "alertId": "alert-uuid"
            }
          }
        ]
      },
      {
        "ruleId": "rule-uuid-3",
        "ruleName": "Financial Health Check",
        "conditionsMet": true,
        "actionsExecuted": [
          {
            "type": "add_risk_score",
            "value": 12
          }
        ]
      }
    ],
    "flags": [
      {
        "type": "ADVERSE_MEDIA",
        "severity": "warning",
        "reason": "3 adverse media articles found",
        "confidence": 0.88
      },
      {
        "type": "HIGH_RISK_JURISDICTION",
        "severity": "critical",
        "reason": "Shareholder 'Investment Holdings LLC' in high-risk jurisdiction",
        "confidence": 0.95
      }
    ]
  },
  "rulesTriggered": 5,
  "executionTimeMs": 2100
}

Step 6: Shareholder Risk Aggregation

How Shareholder Risk Affects Company Risk

Companies can configure rules that evaluate shareholder risk: Example Rule: “High-Risk Shareholder Alert”

{
  "name": "High-Risk Shareholder Alert",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "shareholders.riskScore",
        "operator": "greater_than",
        "value": 70
      },
      {
        "field": "shareholders.ownershipPercentage",
        "operator": "greater_than",
        "value": 10
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 40
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Company has high-risk shareholder with significant ownership"
    }
  ]
}

Querying Company with Shareholders

Endpoint: GET /entities/:companyId?include=shareholders Response:

{
  "entity": {
    "id": "company-uuid",
    "type": "company",
    "name": "Acme Corporation",
    "riskScore": "62.00",
    "shareholders": [
      {
        "id": "shareholder-1-uuid",
        "type": "person",
        "name": "Jane Smith",
        "ownershipPercentage": 35,
        "riskScore": "25.00",
        "relationshipMetadata": {
          "position": "CEO",
          "since": "2015-03-10"
        }
      },
      {
        "id": "shareholder-2-uuid",
        "type": "company",
        "name": "Investment Holdings LLC",
        "ownershipPercentage": 40,
        "riskScore": "78.00",
        "countryCode": "KY",
        "relationshipMetadata": {
          "since": "2018-06-01"
        }
      }
    ]
  }
}

Step 7: Update by External ID

For companies created via external systems, you can update using external ID: Endpoint: PATCH /entities/by-external-id/:externalId Request:

{
  "entityData": {
    "company": {
      "revenue": 30000000,
      "employees": 200,
      "status": "active"
    }
  },
  "metadata": {
    "lastUpdated": "2025-12-24T10:00:00Z",
    "source": "CRM"
  }
}

Use Cases:

Sync company data from CRM
Update financial data from accounting system
Update status from business registry

Best Practices

Use Automatic Creation with Shareholders: Enable createShareholders: true to build complete ownership structure automatically.
Set Appropriate Depth: Use maxShareholderDepth: 3 to prevent excessive recursion while capturing important ownership layers.
Provider Selection: For companies, prioritize:
- Company registry (must-have)
- Beneficial ownership databases (for UBO discovery)
- Sanctions screening
- Adverse media
- Financial data providers
Risk Matrix Configuration: Configure company-specific rules that evaluate:
- Direct company risk factors
- Shareholder risk (individual and aggregate)
- Ownership complexity
- Jurisdictional risk
Shareholder Monitoring: Set up rules to monitor shareholder changes and trigger re-analysis.
Cost Management: Shareholder creation with enrichment can be expensive. Monitor provider costs and set maxCostCents limits.
Periodic Re-enrichment: Company data changes over time. Schedule periodic re-enrichment for active companies.
External ID Mapping: Always set externalId when creating companies from external systems for easy updates.

Error Handling

Shareholder Creation Failures

If shareholder creation fails during automatic creation:

Main company entity is still created
Partial shareholder data may be stored
Error details in response

Example:

{
  "entity": {...},
  "shareholders": [
    {
      "name": "Jane Smith",
      "status": "created",
      "id": "uuid"
    },
    {
      "name": "Investment Holdings LLC",
      "status": "failed",
      "error": "Insufficient data to create entity"
    }
  ],
  "warnings": [
    "Failed to create 1 of 2 shareholders"
  ]
}

Incomplete Ownership Data

If enrichment providers don’t return shareholder data:

{
  "enrichmentResult": {
    "success": true,
    "shareholders": [],
    "warnings": [
      "No shareholder data found from providers"
    ]
  }
}

Solution:

Manually add shareholders using POST /entities + POST /entity-relationships
Try additional beneficial ownership providers

Recursive Depth Limit

If ownership structure exceeds maxShareholderDepth:

{
  "shareholders": [...],
  "warnings": [
    "Maximum shareholder depth reached (3 levels). Deeper shareholders not created."
  ]
}

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

​Flow Diagram

​Step 1: Create Company Entity

​Option A: Automatic Creation (Recommended)

​Option B: Manual Creation

​Step 2: Enrich and Analyze (Manual Flow)

​Step 3: Shareholder Discovery and Creation

​Automatic Shareholder Creation (via /entities/automatic)

​Manual Shareholder Creation

​Step 4: Enrichment Process (Company-Specific)

​Company Enrichment Providers

​Enrichment Result (Company)

​Step 5: Risk Analysis (Company-Specific)

​Company Risk Rules Examples

​Risk Analysis with Shareholder Risk

​Step 6: Shareholder Risk Aggregation

​How Shareholder Risk Affects Company Risk

​Querying Company with Shareholders

​Step 7: Update by External ID

​Best Practices

​Error Handling

​Shareholder Creation Failures

​Incomplete Ownership Data

​Recursive Depth Limit

​Next Steps

Overview

Flow Diagram

Step 1: Create Company Entity

Option A: Automatic Creation (Recommended)

Option B: Manual Creation

Step 2: Enrich and Analyze (Manual Flow)

Step 3: Shareholder Discovery and Creation

Automatic Shareholder Creation (via /entities/automatic)

Manual Shareholder Creation

Step 4: Enrichment Process (Company-Specific)

Company Enrichment Providers

Enrichment Result (Company)

Step 5: Risk Analysis (Company-Specific)

Company Risk Rules Examples

Risk Analysis with Shareholder Risk

Step 6: Shareholder Risk Aggregation

How Shareholder Risk Affects Company Risk

Querying Company with Shareholders

Step 7: Update by External ID

Best Practices

Error Handling

Shareholder Creation Failures

Incomplete Ownership Data

Recursive Depth Limit

Next Steps