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

# Entity Types

> Available entity types in the universal entity system — in the gu1 universal entity model for KYC, KYB, and risk analysis, with examples for entity types use.

## Overview

The Gu1 platform uses a universal entity system where different types of entities can be created, tracked, and monitored. All entities share the same base structure but have type-specific data fields.

## Core Entity Types

### Person

Individual customers, employees, or any natural person.

**Use Cases:**

* Customer onboarding (KYC)
* Employee screening
* Beneficial owner identification
* PEP screening

**Example:**

```json theme={null}
{
  "entityType": "person",
  "entityData": {
    "person": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1990-01-15",
      "nationality": "BR"
    }
  }
}
```

### Company

Business entities, organizations, or legal entities.

**Use Cases:**

* Business verification (KYB)
* Corporate due diligence
* Supplier screening
* Sanctions screening

**Example:**

```json theme={null}
{
  "entityType": "company",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions Ltda",
      "registrationNumber": "12.345.678/0001-90",
      "incorporationDate": "2020-01-15"
    }
  }
}
```

## Financial Entity Types

### payment\_method

Credit cards, bank accounts, wallets, or any payment instrument associated with a person or company.

**Use Cases:**

* Payment fraud detection
* Card verification
* Account monitoring
* Transaction source tracking

**Example:**

```json theme={null}
{
  "entityType": "payment_method",
  "entityData": {
    "paymentMethod": {
      "type": "credit_card",
      "last4": "4242",
      "brand": "visa",
      "expiryMonth": "12",
      "expiryYear": "2025",
      "holderName": "John Doe",
      "issuerCountry": "BR"
    }
  }
}
```

**Related Entities:**

* Link to `person` or `company` owner
* Link to `transaction` entities for usage history
* Link to `device` for fraud detection

### account

Bank accounts, wallets, or financial accounts.

**Example:**

```json theme={null}
{
  "entityType": "account",
  "entityData": {
    "account": {
      "accountNumber": "12345-6",
      "accountType": "checking",
      "bank": "Banco do Brasil",
      "currency": "BRL"
    }
  }
}
```

### card

Specific card entities (alternative to payment\_method).

### transaction

Financial transactions (can also use transactions table).

## Digital Entity Types

### device

Devices used for transactions or account access.

**Use Cases:**

* Device fingerprinting
* Fraud detection
* Multi-device monitoring
* Geographic anomaly detection

**Example:**

```json theme={null}
{
  "entityType": "device",
  "entityData": {
    "device": {
      "deviceId": "abc123",
      "type": "mobile",
      "os": "iOS",
      "osVersion": "17.1",
      "browser": "Safari",
      "ipAddress": "192.168.1.1"
    }
  }
}
```

### location

Physical addresses, IP addresses, or GPS coordinates.

**Example:**

```json theme={null}
{
  "entityType": "location",
  "entityData": {
    "location": {
      "type": "physical_address",
      "street": "Av Paulista, 1000",
      "city": "São Paulo",
      "state": "SP",
      "country": "BR",
      "postalCode": "01310-100",
      "coordinates": {
        "lat": -23.561414,
        "lng": -46.655881
      }
    }
  }
}
```

### document

Documents associated with entities (IDs, passports, contracts).

## Compliance Entity Types

### alert

System-generated alerts from rules engine (also tracked in alerts table).

### investigation

Formal investigations created from alerts or manually.

### case

Investigation cases for compliance review.

### incident

Security or compliance incidents.

### review\_task

Manual review tasks requiring human attention.

### kyc\_document

KYC verification documents.

### compliance\_report

Generated compliance reports.

### risk\_assessment

Risk assessment results.

## Network Entity Types

### network

Social networks, business networks, or relationship graphs.

### relationship

Complex relationships between entities.

## How to Create Entities

All entity types are created using the universal entities endpoint:

```bash theme={null}
POST http://api.gu1.ai/entities
```

**Example: Create a payment method entity**

```bash theme={null}
curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityType": "payment_method",
    "entityData": {
      "paymentMethod": {
        "type": "credit_card",
        "last4": "4242",
        "brand": "visa",
        "expiryMonth": "12",
        "expiryYear": "2025",
        "holderName": "John Doe"
      }
    },
    "relationships": [
      {
        "targetEntityId": "person-uuid-123",
        "relationshipType": "owns",
        "strength": 1.0
      }
    ]
  }'
```

## Entity Relationships

Entities can be linked together using relationships:

```json theme={null}
{
  "relationships": [
    {
      "targetEntityId": "entity-uuid",
      "relationshipType": "owns|uses|manages|belongs_to",
      "strength": 0.0-1.0,
      "metadata": {}
    }
  ]
}
```

**Common Relationship Patterns:**

* `person` **owns** `payment_method`
* `person` **uses** `device`
* `company` **has** `person` (employee/director)
* `payment_method` **used\_in** `transaction`
* `person` **lives\_at** `location`

## See Also

* [Create Entity](/en/api-reference/person/create) - Person entities
* [Create Entity](/en/api-reference/company/create) - Company entities
* [Entity Relationships](/en/api-reference/entities/materialize-relationships) - Managing relationships
* [Analyze Entity](/en/api-reference/entities/analyze) - Risk analysis