Skip to main content

​
Overview

The Güeno 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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
{
  "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: 
POST http://api.gu1.ai/entities
Example: Create a payment method entity 
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: 
{
  "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