Create Entity

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

Required Fields

type

string

required

The type of entity to create. Available types:

person - Individual person/customer
company - Business entity

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

required

Tax identification number (validated based on country)

Optional Fields

externalId

string

Your unique identifier for this entity in your system. If not provided, one will be generated automatically.

string | null

Optional primary contact email on the entity row (nullable for existing records).

phone

string | null

Optional primary contact phone on the entity row (nullable for existing records).

nationality

string | null

Optional root-level nationality: ISO 3166-1 alpha-2, or a recognized label the API maps to ISO2. If omitted, the root field may still be derived from entityData.person.nationality or entityData.company.nationality when mappable.

registrationDate

string

Entity registration date in ISO 8601 datetime format (e.g., “2024-01-15T10:30:00Z”)

isClient

boolean

default:false

Whether this entity is a direct client of your organization

status

string

default:"under_review"

Initial status of the entity. Available options:

active - Entity is active and approved
inactive - Entity is inactive
blocked - Entity is blocked from operations
under_review - Entity is under compliance review (default)
suspended - Entity is temporarily suspended
expired - Entity credentials/approval expired
deleted - Soft deleted entity
rejected - Entity was rejected during review

attributes

object

Custom attributes as key-value pairs (only strings and numbers allowed)

entityData

object

Type-specific data structure. See Entity Data Structures section below.

Risk Matrix & Rules Execution

riskMatrixId

string | string[]

One or more risk matrix UUIDs (legacy: a single UUID string). If provided, after creation the system evaluates this entity only against active rules tied to those matrices (unless skipRulesExecution is true). Same semantics as riskMatrixIds when you send a single id as a string.

riskMatrixIds

string[]

Preferred way to pass multiple matrices: ordered list of UUIDs belonging to your organization. When present and non-empty, it takes precedence over riskMatrixId.

skipRulesExecution

boolean

default:false

Set to true to skip automatic rules execution after entity creation. Use this when you want to manually trigger rule evaluation later.

shareholderDepth

number

default:0

For company entities only: How many levels of shareholders to auto-create when creating a company.

0 - None (default)
1 - Direct shareholders only
2 - Direct + nested level 2
3 - Direct + nested levels 2-3
4 - Direct + nested levels 2-4
5 - Direct + nested levels 2-5 (maximum)

Risk Factors (Manual Override)

riskFactors

object

Manual risk factors to override automated scoring. Typically used for internal risk adjustments.Structure:

{
  "reasons": ["string array of risk reasons"],
  "customLabel": {
    "name": "Custom Risk Label",
    "color": "#ff0000",
    "status": "high_risk",
    "minScore": 80,
    "maxScore": 100,
    "severity": "high" // low | medium | high | critical
  },
  "displayRange": {
    "min": 0,
    "max": 100,
    "current": 85,
    "isInfinite": false
  },
  "originalScore": 85,
  "normalizedScore": 85
}

monitoring

object

Optional: per-integration booleans under main so an enrichment can run in watchlist mode (Regtia op 1) for the main entity when listed in autoExecuteIntegrations. Requires org-level monitoring enabled for that integration in Marketplace (e.g. global_gueno_sanctions_enrichment). The relationships key is only used by POST /entities/automatic with depth.Example: { "main": { "global_gueno_sanctions_enrichment": true } }

Auto-Execute Integrations

autoExecuteIntegrations

object

Automatically execute enrichment integrations upon entity creation.Structure:

{
  "executeAllActiveEnrichments": false,
  "enrichments": [
    "ar_nosis_extended_verification_enrichment",
    "ar_bcra_deudas_enrichment",
    "global_complyadvantage_sanctions_enrichment",
    "global_gueno_sanctions_enrichment"
  ]
}

Options:

executeAllActiveEnrichments (boolean) - Execute all active enrichment providers configured in your organization
enrichments (string[]) - Array of specific enrichment provider codes to execute
enrichmentGroupRefs (string[], optional) - Marketplace enrichment group slugs (enrichments only). With executeAllActiveEnrichments: false, groups are resolved and merged with explicit enrichments. With executeAllActiveEnrichments: true, group refs are ignored (not resolved); explicit enrichments may still append after the active set.

Legacy *_check provider codes in enrichments are silently ignored (removed from the request). Use the matching *_enrichment code instead.

Example provider codes (Argentina company — must match ValidProviderCodesEnum string values):

ar_nosis_extended_verification_enrichment — NOSIS extended company enrichment
ar_bcra_deudas_enrichment — BCRA debts enrichment
global_complyadvantage_sanctions_enrichment — ComplyAdvantage sanctions screening
global_gueno_sanctions_enrichment — Gu1 sanctions screening (when configured)

See Provider codes reference for the full list.

Entity Data Structures

Person Entity

Complete schema for person/individual entities (KYC):

{
  "person": {
    "firstName": "string (optional)",
    "lastName": "string (optional)",
    "dateOfBirth": "string (optional) - Format: YYYY-MM-DD",
    "nationality": "string (optional) - ISO 3166-1 alpha-2 country code",
    "occupation": "string (optional)",
    "income": "number (optional)",
    "incomeCurrency": "string (optional) - ISO 4217 currency code",

    // Address - can be string or structured object
    "address": "string | object (optional)",
    // If object format:
    "address": {
      "street": "string (optional)",
      "number": "string (optional)",
      "complement": "string (optional)",
      "neighborhood": "string (optional)",
      "city": "string (optional)",
      "state": "string (optional)",
      "country": "string (optional)",
      "postalCode": "string (optional)"
    },

    // Alternative: individual address fields
    "city": "string (optional)",
    "state": "string (optional)",
    "country": "string (optional)",
    "postalCode": "string (optional)",

    // Contact information
    "email": "string (optional)",
    "phone": "string (optional)",
    "alternativePhone": "string (optional)",

    // Identification
    "idType": "national_id | passport | drivers_license | tax_id | other (optional)",
    "idNumber": "string (optional)",

    // PEP (Politically Exposed Person) screening
    "isPep": "boolean (optional)",
    "pepPosition": "string (optional) - e.g., 'Minister of Finance'",
    "pepCountry": "string (optional) - ISO 3166-1 alpha-2 country code"
  }
}

Company Entity

Complete schema for company/business entities (KYB):

{
  "company": {
    "legalName": "string (optional)",
    "tradeName": "string (optional)",
    "incorporationDate": "string (optional) - Format: YYYY-MM-DD",
    "companySubtype": "merchant | investment_fund | holding | bank | payment_processor | other (optional)",
    "industry": "string (optional)",
    "websiteUrl": "string (optional)",
    "employeeCount": "number (optional)",
    "revenue": "number (optional)",
    "revenueCurrency": "string (optional) - ISO 4217 currency code",

    // Contact information
    "contactInfo": {
      "email": "string (optional)",
      "phone": "string (optional)",
      "alternativePhone": "string (optional)"
    },

    // Address - can be string or structured object
    "address": "string | object (optional)",
    // If object format:
    "address": {
      "street": "string (optional)",
      "number": "string (optional)",
      "complement": "string (optional)",
      "neighborhood": "string (optional)",
      "city": "string (optional)",
      "state": "string (optional)",
      "country": "string (optional)",
      "postalCode": "string (optional)"
    },

    // Alternative: individual address fields
    "city": "string (optional)",
    "state": "string (optional)",
    "country": "string (optional)",
    "postalCode": "string (optional)"
  }
}

Transaction Entity

Complete schema for transaction entities (fraud detection & AML):

{
  "transaction": {
    "transactionId": "string (optional)",
    "type": "string (optional) - e.g., wire_transfer, card_payment, crypto_transfer",
    "status": "string (optional) - e.g., pending, completed, failed, cancelled",
    "amount": "number (optional)",
    "currency": "string (optional) - ISO 4217 currency code",
    "paymentMethod": "string (optional) - e.g., bank_transfer, credit_card, pix, crypto",
    "originEntityId": "string (optional) - Sender entity ID",
    "destinationEntityId": "string (optional) - Recipient entity ID",
    "transactedAt": "string (optional) - ISO 8601 timestamp",
    "riskScore": "number (optional) - Manual risk score override",
    "flagged": "boolean (optional) - Manual flag",
    "category": "string (optional) - Transaction category/purpose",
    "description": "string (optional) - Transaction description"
  }
}

Device Entity

Complete schema for device entities (device fingerprinting):

{
  "device": {
    "type": "string (optional) - e.g., mobile, tablet, desktop, pos_terminal",
    "model": "string (optional) - Device model",
    "manufacturer": "string (optional) - Device manufacturer",
    "serialNumber": "string (optional) - Device serial number",
    "os": "string (optional) - Operating system",
    "lastSeen": "string (optional) - ISO 8601 timestamp",
    "imei": "string (optional) - International Mobile Equipment Identity",
    "carrier": "string (optional) - Mobile carrier/network operator",
    "phoneNumber": "string (optional) - Associated phone number"
  }
}

Payment Method Entity

Complete schema for payment method entities:

{
  "paymentMethod": {
    "type": "string (optional) - e.g., credit_card, debit_card, bank_account, pix, crypto_wallet",
    "issuer": "string (optional) - Card issuer or bank name",
    "lastFour": "string (optional) - Last 4 digits of card/account",
    "expiryDate": "string (optional) - Card expiry date (MM/YY)",
    "isDefault": "boolean (optional) - Is this the default payment method",
    "pixKey": "string (optional) - PIX key (Brazil)",
    "pixKeyType": "string (optional) - PIX key type: email, cpf, cnpj, phone, random",
    "bankName": "string (optional) - Bank name",
    "bankCode": "string (optional) - Bank code/routing number"
  }
}

Location Entity

Complete schema for location/address entities:

{
  "location": {
    "type": "string (optional) - e.g., residence, business, branch, atm, registered_office",

    // Address - can be string or structured object
    "address": "string | object (optional)",
    // If object format:
    "address": {
      "street": "string (optional)",
      "number": "string (optional)",
      "complement": "string (optional)",
      "neighborhood": "string (optional)",
      "city": "string (optional)",
      "state": "string (optional)",
      "country": "string (optional)",
      "postalCode": "string (optional)"
    },

    // Alternative: individual address fields
    "city": "string (optional)",
    "state": "string (optional)",
    "postalCode": "string (optional)",

    // Geographic coordinates
    "coordinates": {
      "lat": "number (required if coordinates provided)",
      "lng": "number (required if coordinates provided)"
    }
  }
}

Document Entity

Complete schema for document entities:

{
  "document": {
    "type": "string (optional) - e.g., passport, id_card, drivers_license, tax_certificate, incorporation_doc",
    "issuer": "string (optional) - Document issuing authority",
    "issueDate": "string (optional) - ISO 8601 date",
    "expiryDate": "string (optional) - ISO 8601 date",
    "documentNumber": "string (optional) - Document identification number"
  }
}

Alert Entity

Complete schema for alert entities:

{
  "alert": {
    "alertNumber": "string (optional) - Unique alert identifier",
    "alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM (optional)",
    "severity": "INFO | WARNING | HIGH | CRITICAL (optional)",
    "status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE (optional)",
    "sourceSystem": "string (optional) - System that generated the alert",
    "triggerRuleId": "string (optional) - Rule ID that triggered the alert",
    "triggerCondition": "string (optional) - Condition description",
    "affectedEntityId": "string (optional) - Primary entity affected",
    "relatedEntityIds": "string[] (optional) - Related entities",
    "alertedAt": "string (optional) - ISO 8601 timestamp when alert was generated",
    "acknowledgedAt": "string (optional) - ISO 8601 timestamp when acknowledged",
    "acknowledgedBy": "string (optional) - User who acknowledged",
    "resolvedAt": "string (optional) - ISO 8601 timestamp when resolved",
    "resolvedBy": "string (optional) - User who resolved",
    "resolutionNotes": "string (optional) - Resolution notes",
    "falsePositiveReason": "string (optional) - Reason if marked as false positive"
  }
}

Generic Address Field

For country-specific address requirements, you can also use the generic address field:

{
  "address": {
    "street": "string (optional)",
    "city": "string (optional)",
    "state": "string (optional)",
    "country": "string (optional)",
    "postalCode": "string (optional)",
    "number": "string (optional)",
    "complement": "string (optional)",
    "neighborhood": "string (optional)"
  }
}

Risk Matrix Execution on Entity Creation

You can automatically execute one or more risk matrices (set of compliance and risk rules) when creating an entity by providing riskMatrixId or riskMatrixIds.

How It Works

Create your risk matrix in the gu1 dashboard or via API
Get the Matrix ID(s) (UUID format: 550e8400-e29b-41d4-a716-446655440000)
Include riskMatrixId or riskMatrixIds in your entity creation request
The system will automatically:
- Create the entity
- Execute all rules in the specified matrix
- Calculate risk scores
- Generate alerts if rules are triggered
- Update entity status based on results

Example: Create Company with Risk Matrix

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions Sociedade Anônima",
      "tradeName": "Tech Solutions",
      "incorporationDate": "2020-06-15",
      "industry": "fintech",
      "revenue": 5000000
    }
  }
}

Example: Create company with multiple risk matrices

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "entityData": {
    "company": {
      "legalName": "Tech Solutions Sociedade Anônima",
      "industry": "fintech"
    }
  }
}

What Happens After Execution

After the matrix executes, the entity response will include:

{
  "success": true,
  "entity": {
    "id": "entity-uuid-here",
    "name": "Tech Solutions S.A.",
    "riskScore": 75,
    "status": "under_review",
    "riskFactors": {
      "originalScore": 75,
      "normalizedScore": 75,
      "reasons": [
        "High-risk industry detected",
        "Company in high-risk jurisdiction"
      ],
      "displayRange": {
        "min": 50,
        "max": 79,
        "current": 75,
        "isInfinite": false
      },
      "customLabel": {
        "name": "⚠️ Medio Riesgo",
        "color": "#f59e0b",
        "status": "under_review",
        "minScore": 50,
        "maxScore": 79,
        "severity": "medium"
      }
    }
  },
  "alerts": [
    {
      "id": "alert-uuid",
      "severity": "WARNING",
      "message": "Company operates in fintech industry - requires enhanced due diligence",
      "ruleId": "rule-industry-check"
    }
  ]
}

Matrix Execution Options

Skip Rules Execution

If you want to create the entity but delay rule execution:

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "skipRulesExecution": true,
  "entityData": { ... }
}

You can manually trigger rule execution later using the /entities/{id}/execute-rules endpoint.

Without Matrix ID

If you don’t provide riskMatrixId or riskMatrixIds, the system will:

Use your organization’s default matrix (if configured)
Or skip rule execution entirely

Combined with Auto-Execute Integrations

You can combine matrix execution with automatic enrichments:

{
  "type": "company",
  "name": "Tech Solutions S.A.",
  "taxId": "30-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": true,
    "enrichments": [
      "global_complyadvantage_sanctions_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "entityData": {
    "company": {
      "legalName": "Tech Solutions Sociedade Anônima",
      "industry": "fintech"
    }
  }
}

Execution Order:

Entity is created
Enrichments execute (per your autoExecuteIntegrations / org config, e.g. ar_nosis_extended_verification_enrichment)
Risk matrix rules evaluate against enriched data
Final risk score calculated
Alerts generated if rules trigger

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"
    }
  }'

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

​Overview

​Endpoint

​Authentication

​Request Body

​Required Fields

​Optional Fields

​Risk Matrix & Rules Execution

​Risk Factors (Manual Override)

​Auto-Execute Integrations

​Entity Data Structures

​Person Entity

​Company Entity

​Transaction Entity

​Device Entity

​Payment Method Entity

​Location Entity

​Document Entity

​Alert Entity

​Generic Address Field

​Risk Matrix Execution on Entity Creation

​How It Works

​Example: Create Company with Risk Matrix

​Example: Create company with multiple risk matrices

​What Happens After Execution

​Matrix Execution Options

​Skip Rules Execution

​Without Matrix ID

​Combined with Auto-Execute Integrations

​Response

​Examples

​Create Person Entity (KYC)

​Create Company Entity (KYB)

​Create Transaction Entity (Fraud Detection)

​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

Required Fields

Optional Fields

Risk Matrix & Rules Execution

Risk Factors (Manual Override)

Auto-Execute Integrations

Entity Data Structures

Person Entity

Company Entity

Transaction Entity

Device Entity

Payment Method Entity

Location Entity

Document Entity

Alert Entity

Generic Address Field

Risk Matrix Execution on Entity Creation

How It Works

Example: Create Company with Risk Matrix

Example: Create company with multiple risk matrices

What Happens After Execution

Matrix Execution Options

Skip Rules Execution

Without Matrix ID

Combined with Auto-Execute Integrations

Response

Examples

Create Person Entity (KYC)

Create Company Entity (KYB)

Create Transaction Entity (Fraud Detection)

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