Create - gu1

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. Main types:

person - Individual person/customer
company - Business entity
device - Device identifier
payment_method - Payment instrument
location - Geographic location
document - Legal document
account - Account/wallet
card - Card information
alert - Risk/compliance alert

Note: For transactions, use the dedicated transactions API endpoint instead.

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

Optional - Custom attributes as key-value pairs for flexible metadataUse this for custom fields that don’t fit in the standard schema (e.g., internal IDs, tags, flags)

entityData

object

Optional - Type-specific data structure. See examples below for each entity type.

When to use entityData?

Optional for basic entity creation - You can create an entity with just type, name, taxId, and countryCode
Required for enrichment and risk analysis - If you want to run compliance checks, you’ll need to provide relevant fields
Can be populated later - You can create a minimal entity first, then update it with full data before running risk analysis

Minimal Example (Person):

{
  "type": "person",
  "name": "John Doe",
  "taxId": "12345678",
  "countryCode": "US"
  // No entityData needed for basic creation
}

Full Example (Person with KYC data):

{
  "type": "person",
  "name": "John Doe",
  "taxId": "12345678",
  "countryCode": "US",
  "entityData": {
    "person": {
      "firstName": "John",
      "lastName": "Doe",
      "dateOfBirth": "1980-01-15",
      "email": "john@example.com",
      "phone": "+1234567890"
    }
  }
}

isClient

boolean

default:"false"

Mark this entity as a client/customer for tracking purposes

riskMatrixId

string

UUID of the risk matrix to execute rules from automatically

skipRulesExecution

boolean

default:"false"

Skip automatic rules execution after entity creation

status

string

default:"under_review"

Initial status for the entity. Options:

active - Entity is active
inactive - Entity is inactive
blocked - Entity is blocked
under_review - Entity is under review (default)
suspended - Entity is suspended
pending_verification - Pending verification
expired - Entity has expired
deleted - Soft deleted
rejected - Entity was rejected

autoExecuteIntegrations

object

Configure automatic execution of integrations (enrichments and checks) when creating the entity.Properties:

executeAllActiveEnrichments (boolean) - Execute all active enrichment integrations
executeAllActiveChecks (boolean) - Execute all active check integrations
enrichments (array) - Array of specific enrichment provider codes to execute (see Provider Codes Reference)
checks (array) - Array of specific check provider codes to execute (see Provider Codes Reference)

Entity Data Structures

Person Entity

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number,
    "incomeCurrency": "string",
    "address": "string | object (see Address Format note)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string",
    "email": "string",
    "phone": "string",
    "alternativePhone": "string",
    "idType": "national_id | passport | drivers_license | tax_id | other",
    "idNumber": "string",
    "isPep": boolean,
    "pepPosition": "string",
    "pepCountry": "string"
  }
}

Company Entity

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other",
    "industry": "string",
    "websiteUrl": "string",
    "employeeCount": number,
    "revenue": number,
    "revenueCurrency": "string",
    "contactInfo": {
      "email": "string",
      "phone": "string",
      "alternativePhone": "string"
    },
    "address": "string | object (see Address Format note)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string"
  }
}

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 person, company, and location entities.

Device Entity

{
  "device": {
    "type": "string",
    "model": "string",
    "manufacturer": "string",
    "serialNumber": "string",
    "os": "string",
    "lastSeen": "ISO8601 timestamp",
    "imei": "string",
    "carrier": "string",
    "phoneNumber": "string"
  }
}

Payment Method Entity

{
  "paymentMethod": {
    "type": "string",
    "issuer": "string",
    "lastFour": "string",
    "expiryDate": "YYYY-MM",
    "isDefault": boolean,
    "pixKey": "string",
    "pixKeyType": "string",
    "bankName": "string",
    "bankCode": "string"
  }
}

Location Entity

{
  "location": {
    "type": "string",
    "address": "string | object (see Address Format note)",
    "city": "string",
    "state": "string",
    "postalCode": "string",
    "coordinates": {
      "lat": number,
      "lng": number
    }
  }
}

Document Entity

{
  "document": {
    "type": "string",
    "issuer": "string",
    "issueDate": "YYYY-MM-DD",
    "expiryDate": "YYYY-MM-DD",
    "documentNumber": "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": "maria.gonzalez@example.com",
      "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"
    }
  }'

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": "maria.gonzalez@example.com",
      "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:

Request AI Analysis - Get automated risk assessment
List Entities - Query your entities
Get Entity Details - Retrieve complete entity information
Apply Rules - Run compliance and risk rules

Getting Started

Use Cases

Webhooks

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Endpoint

​Authentication

​Request Body

​Entity Data Structures

​Person Entity

​Company Entity

​Device Entity

​Payment Method Entity

​Location Entity

​Document Entity

​Alert Entity

​Response

​Examples

​Create Person Entity (KYC)

​Create Company Entity (KYB)

​Response Example

​Error Responses

​400 Bad Request - Invalid Tax ID

​400 Bad Request - Missing Required Fields

​409 Conflict - Duplicate Entity

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Next Steps

Overview

Endpoint

Authentication

Request Body

Entity Data Structures

Person Entity

Company Entity

Device Entity

Payment Method Entity

Location Entity

Document Entity

Alert Entity

Response

Examples

Create Person Entity (KYC)

Create Company Entity (KYB)

Response Example

Error Responses

400 Bad Request - Invalid Tax ID

400 Bad Request - Missing Required Fields

409 Conflict - Duplicate Entity

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

Next Steps