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

# Entities Overview

> Use the gu1 Entities API to create, retrieve, and update companies, individuals, and transactions modeled across KYB, KYC, and AML workflows.

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

<CardGroup cols={2}>
  <Card title="Company" icon="building">
    Corporate entities for KYB analysis
  </Card>

  <Card title="Person" icon="user">
    Individual entities for KYC analysis
  </Card>

  <Card title="Transaction" icon="money-bill-transfer">
    Financial transactions for monitoring
  </Card>

  <Card title="Custom" icon="shapes">
    Any custom entity type for your business
  </Card>
</CardGroup>

## Entity Lifecycle

<Steps>
  <Step title="Creation">
    Entity is created via API with basic information and optional custom data
  </Step>

  <Step title="Enrichment">
    Additional data is added through updates or integrations
  </Step>

  <Step title="Analysis">
    AI-powered risk analysis is automatically generated
  </Step>

  <Step title="Rule Evaluation">
    Risk rules are applied to calculate risk score and generate alerts
  </Step>

  <Step title="Investigation">
    Alerts trigger investigations for manual review
  </Step>

  <Step title="Resolution">
    Entity status is updated based on investigation outcomes
  </Step>
</Steps>

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

<AccordionGroup>
  <Accordion icon="brain" title="AI Analysis">
    Machine learning models analyze entity behavior, patterns, and anomalies
  </Accordion>

  <Accordion icon="sliders" title="Rule-Based Scoring">
    Custom rules evaluate specific conditions and assign risk points
  </Accordion>

  <Accordion icon="shield-check" title="Compliance Checks">
    Sanctions lists, PEPs, adverse media screening results
  </Accordion>

  <Accordion icon="chart-line" title="Historical Behavior">
    Transaction patterns, account activity, and changes over time
  </Accordion>

  <Accordion icon="link" title="Relationship Analysis">
    Connected entities and their risk profiles
  </Accordion>
</AccordionGroup>

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

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

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

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

**Transaction Example:**

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

<CardGroup cols={2}>
  <Card title="Create Entity" icon="plus" href="/api-reference/entities/create">
    POST /entities - Create new entity
  </Card>

  <Card title="Get Entity" icon="eye" href="/api-reference/entities/get">
    GET /entities/:id - Retrieve entity details
  </Card>

  <Card title="List Entities" icon="list" href="/api-reference/entities/list">
    GET /entities - Query entities with filters
  </Card>

  <Card title="Update Entity" icon="pen" href="/api-reference/entities/update">
    PUT /entities/:id - Update entity data
  </Card>

  <Card title="Delete Entity" icon="trash" href="/api-reference/entities/list">
    DELETE /entities/:id - Remove entity
  </Card>

  <Card title="Bulk Import" icon="layer-group" href="/en/api-reference/bulk-imports/import-entities">
    POST /entities/bulk - Import multiple entities
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion icon="key" title="Use External IDs">
    Always set `externalId` to your internal identifier for easy reconciliation and updates
  </Accordion>

  <Accordion icon="tag" title="Consistent Entity Types">
    Use consistent entity type values across your organization (e.g., "company" vs "corporate")
  </Accordion>

  <Accordion icon="globe" title="Set Country Codes">
    Always include ISO country codes for proper risk assessment and compliance checks
  </Accordion>

  <Accordion icon="database" title="Structure Entity Data">
    Organize `entityData` with consistent field names and nested objects for complex data
  </Accordion>

  <Accordion icon="clock-rotate-left" title="Track Updates">
    Use the `updatedAt` timestamp to detect changes and sync with your systems
  </Accordion>

  <Accordion icon="gauge" title="Bulk Operations">
    Use bulk import for creating multiple entities (>10) to improve performance
  </Accordion>
</AccordionGroup>

## Advanced Features

### AI-Powered Analysis

Every entity can have AI-generated risk analysis:

```bash theme={null}
POST /ai-analysis/entity/:entityId
```

Returns comprehensive analysis including:

* Executive summary
* Behavioral patterns
* Risk factors identified
* Recommendations
* Confidence score

[Learn more →](/api-reference/data-ingestion/overview)

### Entity Relationships

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

```json theme={null}
{
  "sourceEntityId": "entity_1",
  "targetEntityId": "entity_2",
  "relationshipType": "owns",
  "strength": 0.85
}
```

### Document Attachments

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

```bash theme={null}
POST /documents/entity/:entityId/upload
```

[Learn more →](/en/api-reference/documents/upload)

## Example Workflows

<CardGroup cols={2}>
  <Card title="KYB Onboarding" icon="building" href="/use-cases/kyb/workflow">
    Complete company onboarding workflow
  </Card>

  <Card title="KYC Verification" icon="id-card" href="/en/use-cases/kyc/complete-flow">
    Individual customer verification process
  </Card>

  <Card title="Transaction Monitoring" icon="money-bill-transfer" href="/en/use-cases/transaction-monitoring/fraud-detection">
    Real-time transaction screening
  </Card>

  <Card title="Ongoing Monitoring" icon="chart-line" href="/quickstart">
    Continuous entity monitoring setup
  </Card>
</CardGroup>

## Next Steps

<Steps>
  <Step title="Create Your First Entity">
    Follow the [Create Entity guide](/api-reference/entities/create) to add an entity
  </Step>

  <Step title="Setup Data Mapping">
    Use [Custom Schemas](/api-reference/data-ingestion/custom-schemas) for structured imports
  </Step>

  <Step title="Configure Rules">
    Apply risk rules through the dashboard to calculate risk scores
  </Step>

  <Step title="Monitor & Act">
    Setup webhooks to receive alerts when risk scores change
  </Step>
</Steps>