Skip to main content
POST
/
entities
Create a person entity
curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'
{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Overview

Creates a new person entity with the specified attributes. Person entities represent individual customers that you want to analyze for risk and compliance (KYC).

​
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
Must be person for creating a person entity
​
externalId
string
Your unique identifier for this person in your system (optional but recommended)
​
name
string
required
Display name for the person
​
countryCode
string
required
ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)
​
taxId
string
Tax identification number (validated based on country)
📋 See Tax ID Formats by Country for accepted formats and validation rules for each country.
​
operationalHours
object | null
Optional root operational hours for KYT rules (outside_entity_operational_hours on transactedAt). Same shape as Create entity: timezone + weekly slots. Timezone enum: Transaction Time Zone Enum.
​
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 - Person-specific data structure (see below)
When to use entityData?
  • Optional for basic entity creation - You can create a person 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 person first, then update it with full data before running risk analysis
Minimal Example:
{
  "type": "person",
  "name": "John Doe",
  "taxId": "12345678",
  "countryCode": "US"
  // No entityData needed for basic creation
}
Full Example (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"
    }
  }
}
​
registrationDate
string
Person registration date in ISO 8601 datetime format (e.g., “2024-01-15T10:30:00Z”)
​
isClient
boolean
default:"false"
Mark this person as a client/customer for tracking purposes
​
riskMatrixId
string | string[]
One or more risk matrix UUIDs (legacy: a single UUID string). If provided, after creation the system evaluates this person 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. See Risk Matrix Execution below.
​
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"
Skip automatic rules execution after person creation. Use this to create the entity first and manually trigger rules later.
​
status
string
default:"under_review"
Initial status for the person. Options:
  • active - Person is active
  • inactive - Person is inactive
  • blocked - Person is blocked
  • under_review - Person is under review (default)
  • suspended - Person is suspended
  • expired - Person record has expired
  • deleted - Soft deleted
  • rejected - Person was rejected
​
autoExecuteIntegrations
object
Configure automatic execution of enrichments when creating the person.Structure:
{
  "executeAllActiveEnrichments": false,
  "enrichments": [
    "ar_renaper_data_enrichment",
    "ar_repet_person_enrichment",
    "global_gueno_sanctions_enrichment"
  ],
  "excludeEnrichments": []
}
Properties:
  • executeAllActiveEnrichments (boolean) - Run all active org enrichments
  • enrichments (string[]) - Enrichment codes to run after create
  • enrichmentGroupRefs (string[], optional) - Marketplace group slugs
  • excludeEnrichments (string[], optional) - Codes to drop from the final set
*_check codes are no longer part of the create contract; legacy payloads that send them are ignored at parse time.See Person provider codes and Create entity.
​
monitoring
object
Optional. Only affects enrichments that support ongoing monitoring (today: global_gueno_sanctions_enrichment). Same semantics as Create entity — monitoring: monitoring.main[code] with { "watchlist": true } (or legacy true), the code in enrichments, and org monitoring ON in Marketplace.

​
Gu1 sanctions monitoring (person)

{
  "type": "person",
  "externalId": "cust_screening_001",
  "name": "María González",
  "countryCode": "AR",
  "taxId": "27-12345678-1",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"]
  }
}

​
Person Entity Data Structure

The entityData.person object should contain: 
{
  "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"
  }
}
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"
}

​
Risk Matrix Execution

You can automatically execute one or more risk matrices (KYC compliance rules) when creating a person by providing riskMatrixId or riskMatrixIds.

​
How It Works

  1. Get your Risk Matrix ID(s) from the gu1 dashboard (format: UUID)
  2. Include riskMatrixId or riskMatrixIds in your creation request
  3. The system will:
    • Create the person entity
    • Execute all KYC rules in the matrix
    • Calculate risk score
    • Generate compliance alerts if needed
    • Update person status based on results

​
Example with Risk Matrix

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "occupation": "Software Engineer"
    }
  }
}

​
Example with multiple risk matrices

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}

​
Combined with enrichments and Gu1 monitoring

Risk matrix + local enrichments + Gu1 sanctions watchlist (same pattern as Create entity): 
{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_renaper_data_enrichment",
      "ar_repet_person_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}
Flow:
  1. Person is created
  2. Listed enrichments run (RENAPER, REPET, Gu1 sanctions)
  3. Gu1 sanctions uses op 1 (watchlist) only when monitoring and Marketplace allow it
  4. Risk matrix rules evaluate collected data
  5. Score and alerts per rules

​
Response

​
success
boolean
Indicates if the person was created successfully
​
entity
object
The created person object including:
  • id - gu1’s internal ID
  • externalId - Your external ID
  • organizationId - Your organization ID
  • type - Always “person”
  • name - Person name
  • riskScore - Initial risk score (0-100)
  • status - Person status
  • entityData - Person-specific data
  • attributes - Custom attributes
  • createdAt - Creation timestamp
  • updatedAt - Last update timestamp
​
rulesResult
object
Result of rules execution (only present when rules ran, e.g. when skipRulesExecution is false and a risk matrix is configured), including:
  • success (boolean) - Whether rules executed successfully
  • rulesTriggered (number) - Number of rules that were triggered
  • alerts (array) - Alerts generated by rules
  • riskScore (number) - Final calculated risk score
  • decision (string) - Final decision (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
  • rulesExecutionSummary (object) - Present when rules ran. See below for structure.
​
rulesExecutionSummary
object
At the root of the response (same as transactions API). Same value as rulesResult.rulesExecutionSummary. Only present when rules ran (e.g. skipRulesExecution is false). Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score. Omitted when rules did not run.
  • rulesHit (array) - Rules whose conditions were met. Each item: name, description, score, priority, category, status (e.g. active, shadow), conditions (array of { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
  • rulesNoHit (array) - Rules that were evaluated but conditions were not met. Same structure as rulesHit (includes configured actions, not executed).
  • actionsExecuted (object) - Aggregated executed actions across all rules that hit: alerts, suggestion (BLOCK | SUSPEND | FLAG, highest weight), status (entity status applied, if any), assignedUser ({ userId }, if any), customKeys (array of strings, optional) — custom action keys from matched rules; for integrations/workflows.
  • totalScore (number) - Sum of score of all rules that hit and are not in shadow status.

​
Example Request

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,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    }
  }'

​
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,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    },
    "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 person creation",
    "details": {
      "missingFields": ["firstName", "lastName"],
      "requiredFields": ["firstName", "lastName", "dateOfBirth"],
      "countryCode": "AR"
    }
  },
  "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"
}

​
Next Steps

After creating a person, you can:
  1. Get Person Details - Retrieve complete person information
  2. List Persons - Query your persons
  3. Update Person - Modify person data
  4. Create KYC Validation - Start KYC verification process