> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete Company (KYB) Flow

> End-to-end guide for creating, enriching, and analyzing company entities with shareholder discovery — in the gu1 KYB workflow for business verification.

## 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

```mermaid theme={null}
graph TD
    A[Create Company] --> B{Automatic Creation?}
    B -->|Yes| C[POST /entities/automatic]
    B -->|No| D[POST /entities]

    C --> E[Basic Enrichment]
    E --> F[Company Created with Data]
    F --> G[Additional Enrichments]

    D --> H[Company Created - Basic Info Only]

    G --> I{Create Shareholders?}
    H --> J{Need Enrichment?}

    I -->|Yes| K[Shareholder Discovery]
    I -->|No| L[Risk Matrix Assignment]

    J -->|Yes| M[POST /entities/:id/analyze with enrichment]
    J -->|No| N{Risk Matrix Assigned?}

    K --> O[For Each Shareholder]
    O --> P{Shareholder Type}

    P -->|Person| Q[Create Person Entity]
    P -->|Company| R[Create Company Entity - Recursive]

    Q --> S[Enrich Person]
    R --> T[Enrich Company]

    T --> U{Max Depth Reached?}
    U -->|No| K
    U -->|Yes| L

    S --> L
    M --> N

    N -->|Yes| V[Auto Risk Analysis]
    N -->|No| W[Manual Risk Analysis]

    V --> X[Risk Score Calculated]
    W --> Y[POST /entities/:id/analyze]
    Y --> X

    X --> Z[Complete]
```

## 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**:

```json theme={null}
{
  "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**:

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

**Response**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "enrichIfNeeded": true,
  "providerCodes": [
    "company_registry_us",
    "sanctions_api",
    "adverse_media",
    "financial_records",
    "beneficial_ownership"
  ],
  "entityType": "company"
}
```

**What happens**:

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

**Response**:

```json theme={null}
{
  "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:

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

**Example Shareholder Data Structure**:

```json theme={null}
{
  "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:

```json theme={null}
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)

```json theme={null}
{
  "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:

1. **Sanctions Screening**: Check if company or shareholders on sanctions lists
2. **High-Risk Jurisdiction**: Check if incorporated or operating in high-risk countries
3. **Adverse Media**: Count negative news articles
4. **Financial Health**: Evaluate credit rating and financial ratios
5. **ESG Risk**: Check ESG scores and controversies
6. **Ownership Structure**: Analyze shareholder risk (complex structures, offshore entities)
7. **Legal Proceedings**: Count active lawsuits and regulatory actions
8. **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**:

```json theme={null}
{
  "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"

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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

1. **Use Automatic Creation with Shareholders**: Enable `createShareholders: true` to build complete ownership structure automatically.

2. **Set Appropriate Depth**: Use `maxShareholderDepth: 3` to prevent excessive recursion while capturing important ownership layers.

3. **Provider Selection**: For companies, prioritize:
   * Company registry (must-have)
   * Beneficial ownership databases (for UBO discovery)
   * Sanctions screening
   * Adverse media
   * Financial data providers

4. **Risk Matrix Configuration**: Configure company-specific rules that evaluate:
   * Direct company risk factors
   * Shareholder risk (individual and aggregate)
   * Ownership complexity
   * Jurisdictional risk

5. **Shareholder Monitoring**: Set up rules to monitor shareholder changes and trigger re-analysis.

6. **Cost Management**: Shareholder creation with enrichment can be expensive. Monitor provider costs and set `maxCostCents` limits.

7. **Periodic Re-enrichment**: Company data changes over time. Schedule periodic re-enrichment for active companies.

8. **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**:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`:

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

## Next Steps

* [Configure Risk Matrix for Companies](/en/api-reference/risk-matrix/list)
* [Shareholder Monitoring Rules](/en/use-cases/kyb/overview)
* [Beneficial Ownership Analysis](/en/use-cases/kyb/workflow)
* [Company Registry Integrations](/en/api-reference/integrations/provider-codes)