Skip to main content

​
Overview

Creates a new entity with the specified type and attributes. Entities represent the core data objects you want to analyze for risk and compliance.

​
Endpoint

POST http://api.gu1.ai/entities

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
type
string
required
The type of entity to create. Available types:
  • person - Individual person/customer
  • company - Business entity
  • transaction - Financial transaction
  • device - Device identifier
  • payment_method - Payment instrument
  • location - Geographic location
  • document - Legal document
  • account - Account/wallet
  • card - Card information
  • alert - Alert/flag
  • custom - Custom entity type
  • other - Other types
​
externalId
string
required
Your unique identifier for this entity in your system
​
name
string
required
Display name for the entity
​
countryCode
string
required
ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)
​
taxId
string
Tax identification number (validated based on country)
​
attributes
object
Custom attributes as key-value pairs
​
entityData
object
Type-specific data structure. See examples below for each entity type.

​
Entity Data Structures

​
Person Entity

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number
  }
}

​
Company Entity

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "industry": "string",
    "employeeCount": number,
    "revenue": number,
    "address": "string | object (see note below)"
  }
}
Address Format: The address field supports both formats:
  • String format (simple): "Av. Paulista, 1000, São Paulo, SP, Brazil"
  • Object format (structured): 
    {
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}
This applies to both person and company entities.

​
Transaction Entity

{
  "transaction": {
    "transactionId": "string",
    "type": "string",
    "status": "string",
    "amount": number,
    "currency": "string",
    "paymentMethod": "string",
    "originEntityId": "string",
    "destinationEntityId": "string",
    "transactedAt": "ISO8601 timestamp",
    "riskScore": number,
    "flagged": boolean,
    "category": "string",
    "description": "string"
  }
}

​
Alert Entity

{
  "alert": {
    "alertNumber": "string",
    "alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM",
    "severity": "INFO | WARNING | HIGH | CRITICAL",
    "status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE",
    "sourceSystem": "string",
    "triggerRuleId": "string",
    "triggerCondition": "string",
    "affectedEntityId": "string",
    "relatedEntityIds": ["string"],
    "alertedAt": "ISO8601 timestamp",
    "acknowledgedAt": "ISO8601 timestamp",
    "acknowledgedBy": "string",
    "resolvedAt": "ISO8601 timestamp",
    "resolvedBy": "string",
    "resolutionNotes": "string",
    "falsePositiveReason": "string"
  }
}

​
Response

​
success
boolean
Indicates if the entity was created successfully
​
entity
object
The created entity object including:
  • id - gu1’s internal ID
  • externalId - Your external ID
  • organizationId - Your organization ID
  • type - Entity type
  • name - Entity name
  • riskScore - Initial risk score (0-100)
  • status - Entity status
  • entityData - Type-specific data
  • attributes - Custom attributes
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp

​
Examples

​
Create Person Entity (KYC)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "externalId": "customer_12345",
    "name": "María González",
    "countryCode": "AR",
    "taxId": "20-12345678-9",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "attributes": {
      "email": "[email protected]",
      "phone": "+54 11 1234-5678",
      "customerSince": "2024-01-15"
    }
  }'

​
Create Company Entity (KYB)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "externalId": "company_789",
    "name": "Tech Solutions S.A.",
    "countryCode": "BR",
    "taxId": "12.345.678/0001-90",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "registeredAddress": "Av. Paulista, 1000, São Paulo",
      "partnershipTier": "gold"
    }
  }'

​
Create Transaction Entity (Fraud Detection)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "transaction",
    "externalId": "txn_98765",
    "name": "Wire Transfer - $50,000",
    "countryCode": "US",
    "entityData": {
      "transaction": {
        "transactionId": "txn_98765",
        "type": "wire_transfer",
        "status": "completed",
        "amount": 50000,
        "currency": "USD",
        "paymentMethod": "bank_transfer",
        "originEntityId": "customer_12345",
        "destinationEntityId": "merchant_456",
        "transactedAt": "2024-10-03T14:30:00Z",
        "category": "business_payment",
        "description": "Payment for professional services"
      }
    }
  }'

​
Response Example

{
  "success": true,
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "person",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 25,
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "attributes": {
      "email": "[email protected]",
      "phone": "+54 11 1234-5678",
      "customerSince": "2024-01-15"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  }
}

​
Error Responses

​
400 Bad Request - Invalid Tax ID

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid CUIT format. Please check the format and try again.",
    "details": {
      "field": "taxId",
      "taxIdName": "CUIT",
      "providedValue": "20-12345678-9"
    }
  },
  "entity": null
}

​
400 Bad Request - Missing Required Fields

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for company creation",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

​
409 Conflict - Duplicate Entity

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "customer_12345",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

​
429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "You have exceeded your API rate limit. Please wait before making more requests.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred while creating the entity",
    "details": {
      "message": "Database connection timeout"
    }
  },
  "entity": null
}

​
Next Steps

After creating an entity, you can:
  1. Request AI Analysis - Get automated risk assessment
  2. List Entities - Query your entities
  3. Get Entity Details - Retrieve complete entity information
  4. Apply Rules - Run compliance and risk rules