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

# Automatic Company Onboarding with Risk Assessment

> Onboard companies automatically with shareholder hierarchy, enrichment, compliance screening, and risk matrix execution in the gu1 automated flow.

## Overview

This guide demonstrates the complete automated onboarding flow for companies (businesses) using gu1's automatic entity creation with integrated risk assessment. The system will:

1. **Fetch official company data** from business registries (e.g., CNPJ in Brazil)
2. **Extract shareholder structure** automatically (up to 5 levels deep)
3. **Create shareholder entities** recursively with their own enrichments
4. **Execute enrichments** for the company and all shareholders
5. **Run compliance enrichments** (sanctions, adverse media, ownership verification)
6. **Execute risk matrix rules** for the company (shareholders can also trigger rules)
7. **Generate alerts and investigations** if rules are triggered
8. **Send notifications** via Socket.IO and webhooks

This is ideal for KYB (Know Your Business) processes where you need complete company verification including beneficial ownership structure.

## Prerequisites

Before starting, you need:

1. **API Key** - Get one from [API Keys (`/org-api-keys`)](https://app.gu1.ai/org-api-keys)
2. **Risk Matrix** - Create and configure a risk matrix with rules for the `entity_created` trigger
3. **Active Integrations** - Enable enrichment providers from the Marketplace
4. **Valid Tax ID** - A real company tax ID from a supported country (e.g., CNPJ for Brazil)

## The Complete Flow

Here's what happens when you create a company automatically with shareholder traversal and risk matrix:

```mermaid theme={null}
sequenceDiagram
    participant API as Your App
    participant Gu1 as gu1 API
    participant Registry as Gov Registry
    participant Providers as Data Providers
    participant Rules as Rules Engine
    participant Notify as Notifications

    API->>Gu1: POST /entities/automatic (depth=2)
    Note over Gu1: 1. Validate request

    Gu1->>Registry: Fetch company data (CNPJ)
    Registry-->>Gu1: Company + shareholders list

    Note over Gu1: 2. Create main entity
    Gu1->>Gu1: Insert company

    Note over Gu1: 3. Execute enrichments (main)
    Gu1->>Providers: serpro_cnpj, receita_federal
    Providers-->>Gu1: Enriched company data

    Note over Gu1: 4. Execute enrichments (main)
    Gu1->>Providers: global_gueno_sanctions_enrichment, br_bdc_negative_media_company_enrichment
    Providers-->>Gu1: Enrichment results

    Note over Gu1: 5. Process shareholders (level 1)
    loop For each shareholder
        Gu1->>Registry: Fetch shareholder data
        Registry-->>Gu1: Shareholder details
        Gu1->>Gu1: Create shareholder entity
        Gu1->>Providers: Execute shareholder enrichments
        Gu1->>Gu1: Create relationship

        alt Shareholder is company & depth > 1
            Note over Gu1: Recursive: Process sub-shareholders
        end
    end

    Note over Gu1: 6. Execute risk matrix (main company)
    Gu1->>Rules: Trigger: entity_created
    Rules->>Rules: Evaluate all rules
    Rules-->>Gu1: Risk score + alerts

    Note over Gu1: 7. Update & notify
    Gu1->>Gu1: Update risk score
    Gu1->>Notify: Socket.IO events
    Gu1->>Notify: Webhook events

    Gu1-->>API: Complete result with hierarchy
```

## Quick Start Example

### Basic Company Onboarding with Shareholders and Risk Assessment

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.gu1.ai/entities/automatic \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "taxId": "12.345.678/0001-90",
      "country": "BR",
      "type": "company",
      "depth": 2,
      "isClient": true,
      "riskMatrixId": "risk_matrix_uuid",
      "autoExecuteIntegrations": {
        "executeAllActiveEnrichments": true,
      },
      "autoExecuteIntegrationsShareholders": {
        "enrichments": {
          "company": ["serpro_cnpj", "receita_federal", "global_gueno_sanctions_enrichment"],
          "person": ["serpro_cpf", "br_amldd_pep_enrichment", "global_gueno_sanctions_enrichment"]
        }
      }
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.gu1.ai/entities/automatic', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      taxId: '12.345.678/0001-90',
      country: 'BR',
      type: 'company',
      depth: 2, // Create shareholders up to 2 levels
      isClient: true,
      riskMatrixId: 'risk_matrix_uuid',
      autoExecuteIntegrations: {
        executeAllActiveEnrichments: true,
      },
      autoExecuteIntegrationsShareholders: {
        enrichments: {
          company: ['serpro_cnpj', 'receita_federal', 'global_gueno_sanctions_enrichment'],
          person: ['serpro_cpf', 'br_amldd_pep_enrichment', 'global_gueno_sanctions_enrichment']
        }
      }
    })
  });

  const result = await response.json();
  console.log('Company created:', result.data.entity);
  console.log('Shareholders created:', result.data.summary.entitiesCreated - 1);
  console.log('Risk score:', result.rulesResult?.result?.riskScore);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.gu1.ai/entities/automatic',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'taxId': '12.345.678/0001-90',
          'country': 'BR',
          'type': 'company',
          'depth': 2,
          'isClient': True,
          'riskMatrixId': 'risk_matrix_uuid',
          'autoExecuteIntegrations': {
              'executeAllActiveEnrichments': True,
          },
          'autoExecuteIntegrationsShareholders': {
              'enrichments': {
                  'company': ['serpro_cnpj', 'receita_federal', 'global_gueno_sanctions_enrichment'],
                  'person': ['serpro_cpf', 'br_amldd_pep_enrichment', 'global_gueno_sanctions_enrichment']
              }
          }
      }
  )

  result = response.json()
  print('Company created:', result['data']['entity'])
  print('Shareholders created:', result['data']['summary']['entitiesCreated'] - 1)
  print('Risk score:', result['rulesResult']['result']['riskScore'])
  ```
</CodeGroup>

## Complete Response Example

When the process completes successfully, you'll receive a comprehensive response with the full ownership structure:

```json theme={null}
{
  "success": true,
  "data": {
    "entity": {
      "id": "company_uuid_abc123",
      "organizationId": "org_uuid",
      "type": "company",
      "name": "Tech Solutions Ltda",
      "taxId": "12345678000190",
      "countryCode": "BR",
      "status": "under_review",
      "riskScore": 42,
      "isClient": true,
      "entityData": {
        "company": {
          "legalName": "Tech Solutions Ltda",
          "tradeName": "Tech Solutions",
          "incorporationDate": "2020-01-15",
          "industryCode": "6201-5/00",
          "legalNature": "206-2",
          "companySize": "MEDIUM"
        }
      },
      "enrichmentData": {
        "serpro_cnpj": {
          "status": "ATIVA",
          "situation": "REGULAR",
          "capitalSocial": "500000.00"
        },
        "receita_federal": {
          "taxCompliance": "REGULAR",
          "debts": false
        },
        "global_gueno_sanctions_enrichment": {
          "hasMatches": false
        },
        "br_bdc_negative_media_company_enrichment": {
          "hasNegativeMedia": false
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:12.000Z"
    },
    "summary": {
      "entitiesCreated": 5,
      "relationshipsCreated": 4,
      "errorsCount": 0
    },
    "entitiesCreatedDetails": [
      {
        "id": "person_uuid_001",
        "name": "João Silva",
        "taxId": "12345678900",
        "type": "person"
      },
      {
        "id": "person_uuid_002",
        "name": "Maria Santos",
        "taxId": "98765432100",
        "type": "person"
      },
      {
        "id": "company_uuid_002",
        "name": "Holdings ABC Ltda",
        "taxId": "98765432000101",
        "type": "company"
      },
      {
        "id": "person_uuid_003",
        "name": "Carlos Costa",
        "taxId": "11122233344",
        "type": "person"
      }
    ]
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "result": {
      "entityId": "company_uuid_abc123",
      "entityType": "company",
      "riskScore": 42,
      "overallConfidence": 0.92,
      "totalRules": 15,
      "successfulRules": 4,
      "failedRules": 0,
      "rulesExecuted": [
        {
          "ruleId": "rule_company_age",
          "ruleName": "New Company (< 2 years)",
          "matched": true,
          "score": 25,
          "confidence": 1.0
        },
        {
          "ruleId": "rule_ownership_complexity",
          "ruleName": "Complex Ownership Structure",
          "matched": true,
          "score": 15,
          "confidence": 0.85
        },
        {
          "ruleId": "rule_pep_shareholders",
          "ruleName": "PEP in Shareholder Structure",
          "matched": false,
          "score": 0,
          "confidence": 1.0
        },
        {
          "ruleId": "rule_sanctions_company",
          "ruleName": "Sanctions screening - Company",
          "matched": false,
          "score": 0,
          "confidence": 1.0
        }
      ],
      "flags": [
        {
          "type": "OWNERSHIP_VERIFIED",
          "severity": "INFO",
          "message": "Beneficial ownership structure mapped to 2 levels"
        },
        {
          "type": "NEW_COMPANY",
          "severity": "WARNING",
          "message": "Company incorporated less than 2 years ago"
        }
      ]
    },
    "executionTimeMs": 5230,
    "rulesTriggered": 2
  }
}
```

## Understanding Shareholder Traversal

### The `depth` Parameter

The `depth` parameter controls how many levels of the ownership structure to traverse:

* **depth: 0** - Only create the main company (no shareholders)
* **depth: 1** - Create main company + direct shareholders (1 level)
* **depth: 2** - Create main company + shareholders + their shareholders (2 levels)
* **depth: 3-5** - Continue recursively up to 5 levels

```javascript theme={null}
// Example: depth = 2
// Main Company (Tech Solutions Ltda)
//   ├─ João Silva (60%) - Person
//   ├─ Holdings ABC Ltda (40%) - Company
//   │   ├─ Maria Santos (70%) - Person
//   │   └─ Carlos Costa (30%) - Person
// Total entities created: 5 (1 main + 4 shareholders)
// Total relationships created: 4
```

### Shareholder-Specific Integrations

You can configure different integrations for company vs person shareholders:

```javascript theme={null}
autoExecuteIntegrationsShareholders: {
  enrichments: {
    company: ['serpro_cnpj', 'receita_federal', 'global_gueno_sanctions_enrichment', 'br_bdc_negative_media_company_enrichment'],
    person: ['serpro_cpf', 'br_amldd_pep_enrichment', 'global_gueno_sanctions_enrichment']
  }
}
```

This is more efficient than running all enrichments on everyone.

## Step-by-Step Implementation

### Step 1: Set Up Your Risk Matrix for Companies

Create a risk matrix specifically for company onboarding:

```javascript theme={null}
const riskMatrix = await fetch('https://api.gu1.ai/risk-matrices', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Company Onboarding Risk Matrix',
    description: 'Evaluate risk for new company entities',
    enabled: true,
    rules: [
      {
        name: 'New Company Flag',
        description: 'Flag companies less than 2 years old',
        condition: `
          const incorporationDate = new Date(enrichment.serpro_cnpj?.incorporationDate);
          const now = new Date();
          const ageYears = (now - incorporationDate) / (1000 * 60 * 60 * 24 * 365);
          return ageYears < 2;
        `,
        score: 25,
        severity: 'MEDIUM',
        triggers: ['entity_created'],
        targetEntityTypes: ['company'],
        enabled: true
      },
      {
        name: 'Sanctions screening - Company',
        description: 'Flag if company is in sanctions lists',
        condition: 'enrichment.global_gueno_sanctions_enrichment.hasMatches === true',
        score: 100,
        severity: 'CRITICAL',
        triggers: ['entity_created'],
        targetEntityTypes: ['company'],
        enabled: true
      },
      {
        name: 'Complex Ownership',
        description: 'Flag companies with complex ownership structures',
        condition: `
          const shareholderCount = context.relationships?.length || 0;
          return shareholderCount > 10;
        `,
        score: 15,
        severity: 'LOW',
        triggers: ['entity_created'],
        targetEntityTypes: ['company'],
        enabled: true
      },
      {
        name: 'High Risk Industry',
        description: 'Flag companies in high-risk industries',
        condition: `
          const highRiskIndustries = ['6201', '6202', '6463', '6491'];
          const industryCode = enrichment.serpro_cnpj?.industryCode?.substring(0, 4);
          return highRiskIndustries.includes(industryCode);
        `,
        score: 30,
        severity: 'HIGH',
        triggers: ['entity_created'],
        targetEntityTypes: ['company'],
        enabled: true
      }
    ]
  })
});

const { id: riskMatrixId } = await riskMatrix.json();
console.log('Risk Matrix created:', riskMatrixId);
```

### Step 2: Create Company with Full Ownership Structure

```javascript theme={null}
async function onboardCompanyWithOwnership(cnpj, depth = 2) {
  const response = await fetch('https://api.gu1.ai/entities/automatic', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      taxId: cnpj,
      country: 'BR',
      type: 'company',
      depth: depth,
      externalId: `business_${Date.now()}`,
      isClient: true,
      riskMatrixId: 'your_risk_matrix_id',
      status: 'under_review',

      // Main company integrations
      autoExecuteIntegrations: {
        enrichments: [
          'serpro_cnpj',
          'receita_federal',
          'serasa_company',
          'global_gueno_sanctions_enrichment',
          'br_bdc_negative_media_company_enrichment'
        ]
      },

      // Shareholder integrations (differentiated by type)
      autoExecuteIntegrationsShareholders: {
        enrichments: {
          company: [
            'serpro_cnpj',
            'receita_federal',
            'global_gueno_sanctions_enrichment'
          ],
          person: [
            'serpro_cpf',
            'br_amldd_pep_enrichment',
            'global_gueno_sanctions_enrichment'
          ]
        }
      }
    })
  });

  const result = await response.json();

  if (!result.success) {
    throw new Error(result.error);
  }

  return result;
}

// Usage
try {
  const result = await onboardCompanyWithOwnership('12.345.678/0001-90', 2);

  console.log('✅ Company onboarded successfully!');
  console.log('Main Entity:', result.data.entity.name);
  console.log('Risk Score:', result.rulesResult?.result?.riskScore);
  console.log('Entities Created:', result.data.summary.entitiesCreated);
  console.log('Relationships Created:', result.data.summary.relationshipsCreated);

  // Log ownership structure
  console.log('\n📊 Ownership Structure:');
  result.data.entitiesCreatedDetails.forEach((entity, index) => {
    console.log(`  ${index + 1}. ${entity.name} (${entity.type}) - ${entity.taxId}`);
  });

  // Check for errors
  if (result.data.errors) {
    const totalErrors =
      result.data.errors.creationFailed.length +
      result.data.errors.enrichmentFailed.length;

    if (totalErrors > 0) {
      console.log('\n⚠️  Partial failures detected:');
      result.data.errors.creationFailed.forEach(err => {
        console.log(`  - Failed to create: ${err.name} (${err.taxId})`);
      });
      result.data.errors.enrichmentFailed.forEach(err => {
        console.log(`  - Enrichment failed: ${err.name} (${err.taxId})`);
      });
    }
  }

} catch (error) {
  console.error('❌ Onboarding failed:', error.message);
}
```

### Step 3: Visualize Ownership Structure

After creating the company, fetch and visualize the ownership graph:

```javascript theme={null}
async function getOwnershipStructure(companyId) {
  // Fetch entity with relationships
  const response = await fetch(
    `https://api.gu1.ai/entities/${companyId}?includeRelationships=true`,
    {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY'
      }
    }
  );

  const { entity, relationships } = await response.json();

  // Build ownership tree
  const tree = buildOwnershipTree(entity, relationships);
  return tree;
}

function buildOwnershipTree(entity, relationships, level = 0) {
  const indent = '  '.repeat(level);
  let tree = `${indent}${entity.name} (${entity.type})\n`;

  // Find shareholders of this entity
  const shareholders = relationships.filter(
    rel => rel.fromEntityId === entity.id && rel.relationshipType === 'shareholder'
  );

  shareholders.forEach(rel => {
    const percentage = rel.metadata?.ownershipPercentage || 0;
    tree += `${indent}  ├─ ${rel.toEntity.name} (${percentage}%)\n`;

    // Recursively get sub-shareholders if available
    if (rel.toEntity.relationships) {
      tree += buildOwnershipTree(rel.toEntity, rel.toEntity.relationships, level + 2);
    }
  });

  return tree;
}

// Usage
const structure = await getOwnershipStructure('company_uuid_abc123');
console.log('Ownership Structure:\n', structure);

// Output:
// Tech Solutions Ltda (company)
//   ├─ João Silva (60%)
//   ├─ Holdings ABC Ltda (40%)
//     ├─ Maria Santos (70%)
//     └─ Carlos Costa (30%)
```

### Step 4: Handle Complex Scenarios

#### Scenario 1: Circular Ownership Detection

The system automatically prevents circular ownership loops:

```javascript theme={null}
// Company A → Company B → Company A (circular)
// System will detect and stop at the second occurrence of Company A
```

#### Scenario 2: Large Shareholder Structures

For companies with many shareholders (e.g., 50+), consider:

```javascript theme={null}
// Option 1: Limit depth to reduce processing time
depth: 1  // Only direct shareholders

// Option 2: Use specific enrichments only
autoExecuteIntegrationsShareholders: {
  enrichments: {
    company: ['serpro_cnpj'],
    person: ['serpro_cpf']
  }
}

// Option 3: Skip shareholders entirely for initial creation
depth: 0  // Create company only, add shareholders later
```

#### Scenario 3: Foreign Shareholders

When shareholders are from different countries:

```javascript theme={null}
// The system will:
// 1. Detect country from taxId format
// 2. Use country-specific providers automatically
// 3. Create relationships with country metadata

// Example: Brazilian company with US shareholder
// Main: BR company → uses serpro_cnpj
// Shareholder: US person → uses us_ssn_lookup (if available)
```

## Real-Time Updates for Company Creation

Listen for events during the onboarding process:

```javascript theme={null}
import { io } from 'socket.io-client';

const socket = io('https://api.gu1.ai', {
  auth: { token: 'YOUR_API_KEY' },
  query: { organizationId: 'your_org_id' }
});

// Track creation progress
let entitiesCreated = 0;
let shareholdersCreated = 0;

socket.on('entity:creation-started', (data) => {
  console.log('🚀 Starting creation:', data.taxId);
});

socket.on('entity:creation-completed', (data) => {
  entitiesCreated++;

  if (data.isMainEntity) {
    console.log('✅ Main company created:', data.mainEntityName);
  } else {
    shareholdersCreated++;
    console.log(`  ├─ Shareholder ${shareholdersCreated} created:`, data.mainEntityName);
  }

  // Update progress bar
  updateProgress(entitiesCreated, shareholdersCreated);
});

socket.on('risk-matrix:executed', (data) => {
  console.log('🎯 Risk assessment:', {
    riskScore: data.riskScore,
    status: data.newStatus,
    alerts: data.alertsGenerated
  });
});

socket.on('investigation:created', (data) => {
  console.log('🔍 Investigation opened:', {
    id: data.investigationId,
    priority: data.priority,
    reason: 'Multiple alerts consolidated'
  });
});
```

## Understanding Risk Assessment for Companies

### Company-Specific Risk Factors

Companies are evaluated differently than persons:

```javascript theme={null}
// Rule examples for companies
{
  // Age of company
  condition: `
    const ageYears = (new Date() - new Date(enrichment.serpro_cnpj.incorporationDate)) / 31536000000;
    return ageYears < 2;
  `,
  score: 25,
  severity: 'MEDIUM'
}

{
  // Capital social (authorized capital)
  condition: `
    const capital = parseFloat(enrichment.serpro_cnpj.capitalSocial);
    return capital < 10000; // Less than R$ 10k
  `,
  score: 20,
  severity: 'MEDIUM'
}

{
  // Industry risk
  condition: `
    const highRiskCodes = ['6201', '6463', '6491'];
    return highRiskCodes.includes(enrichment.serpro_cnpj.industryCode?.substring(0, 4));
  `,
  score: 30,
  severity: 'HIGH'
}

{
  // Ownership complexity
  condition: `
    const shareholderCount = context.relationships?.length || 0;
    const hasIndirectOwners = context.relationships?.some(r => r.level > 1);
    return shareholderCount > 10 || hasIndirectOwners;
  `,
  score: 15,
  severity: 'LOW'
}
```

### Shareholder Risk Propagation

Risks from shareholders can affect the main company:

```javascript theme={null}
// Example: If any shareholder is PEP, flag the company
{
  name: 'PEP in Ownership Structure',
  condition: `
    // Check all shareholders
    const shareholders = context.shareholders || [];
    return shareholders.some(s => s.enrichmentData?.br_amldd_pep_enrichment?.isPep === true);
  `,
  score: 40,
  severity: 'HIGH',
  targetEntityTypes: ['company']
}
```

## Best Practices

### 1. Choose Appropriate Depth

```javascript theme={null}
// ✅ Good: Most common use cases
depth: 0  // No shareholders - fastest, company only
depth: 1  // Direct shareholders only - balanced
depth: 2  // Two levels - complete for most cases

// ⚠️  Use carefully: Expensive operations
depth: 3  // Three levels - slow, many entities
depth: 4-5  // Very deep - only for specific compliance requirements
```

### 2. Differentiate Shareholder Integrations

```javascript theme={null}
// ❌ Bad: Same enrichments for everyone (expensive)
autoExecuteIntegrationsShareholders: {
  executeAllActiveEnrichments: true,
}

// ✅ Good: Targeted enrichments by entity type
autoExecuteIntegrationsShareholders: {
  enrichments: {
    company: ['serpro_cnpj', 'global_gueno_sanctions_enrichment'],
    person: ['serpro_cpf', 'br_amldd_pep_enrichment']
  }
}
```

### 3. Handle Partial Failures Gracefully

```javascript theme={null}
if (result.success) {
  const { errors } = result.data;

  // Main entity always succeeds, but shareholders might fail
  if (errors.creationFailed.length > 0) {
    console.warn(`${errors.creationFailed.length} shareholders failed to create`);

    // You can:
    // 1. Continue with the main company
    // 2. Retry failed shareholders individually
    // 3. Flag for manual review
  }

  if (errors.enrichmentFailed.length > 0) {
    console.warn(`${errors.enrichmentFailed.length} entities had enrichment failures`);

    // Entity exists but some data is missing
    // You can retry enrichments later
  }
}
```

### 4. Monitor Performance

```javascript theme={null}
// Track creation time
const startTime = Date.now();

const result = await onboardCompany(cnpj, depth);

const duration = Date.now() - startTime;
const entitiesPerSecond = result.data.summary.entitiesCreated / (duration / 1000);

console.log(`Created ${result.data.summary.entitiesCreated} entities in ${duration}ms`);
console.log(`Performance: ${entitiesPerSecond.toFixed(2)} entities/second`);

// Typical performance:
// depth=0: 2-5 seconds (company only)
// depth=1: 5-15 seconds (5-10 entities)
// depth=2: 15-45 seconds (10-50 entities)
```

## Troubleshooting

### Issue: Timeout Errors

```javascript theme={null}
// Problem: Request times out with depth=3+
// Solution: Reduce depth or use fewer integrations

// Option 1: Reduce depth
depth: 1

// Option 2: Skip shareholder enrichments beyond basic registry data
autoExecuteIntegrationsShareholders: {
  enrichments: {
    company: ['serpro_cnpj'],
    person: ['serpro_cpf']
  }
}
```

### Issue: Too Many Entities Created

```javascript theme={null}
// Problem: Created 100+ entities from deep structure
// Solution: Limit depth and review structure

// Check the response
console.log('Total entities:', result.data.summary.entitiesCreated);

// If too many, recreate with depth=1
if (result.data.summary.entitiesCreated > 50) {
  console.log('Structure too large, reducing depth');
  result = await onboardCompany(cnpj, 1);  // Only direct shareholders
}
```

### Issue: Circular Ownership Detected

```javascript theme={null}
// The system automatically prevents circular references
// but logs them in the response

if (result.data.warnings?.includes('CIRCULAR_OWNERSHIP')) {
  console.log('Circular ownership detected - stopped at:',
    result.data.warnings.circularAt);
}
```

## Related Documentation

<CardGroup cols={2}>
  <Card title="Company API Reference" icon="building" href="/en/api-reference/company/create-automatic">
    Complete API documentation for company creation
  </Card>

  <Card title="Person Onboarding" icon="user" href="/en/use-cases/onboarding/person-automatic-with-risk-matrix">
    Learn about person entity onboarding
  </Card>

  <Card title="Risk Matrix Guide" icon="shield" href="/en/api-reference/risk-matrix/list">
    Configure risk matrices and rules
  </Card>

  <Card title="Relationships API" icon="diagram-project" href="/en/api-reference/entities/materialize-relationships">
    Work with entity relationships
  </Card>
</CardGroup>