Create

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.

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

UUID of the risk matrix to execute rules from automatically. See Risk Matrix Execution section below for details.

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 integrations (enrichments and checks) when creating the person.Structure:

{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": ["NOSIS"],
  "checks": ["COMPLY_ADVANTAGE", "REPET"]
}

Properties:

executeAllActiveEnrichments (boolean) - Execute all active enrichment integrations configured in your organization
executeAllActiveChecks (boolean) - Execute all active check integrations configured in your organization
enrichments (string[]) - Array of specific enrichment provider codes to execute
checks (string[]) - Array of specific check provider codes to execute

Common Provider Codes:

NOSIS - NOSIS Argentina (person identity & credit data)
REPET - REPET Argentina (watchlist screening)
COMPLY_ADVANTAGE - ComplyAdvantage (sanctions & PEP screening)
WORLDCHECK - Refinitiv World-Check (compliance screening)

See Provider Codes Reference for complete list.

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 a risk matrix (KYC compliance rules) when creating a person by providing the riskMatrixId parameter.

How It Works

Get your Risk Matrix ID from the gu1 dashboard (format: UUID)
Include riskMatrixId in your creation request
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"
    }
  }
}

Combined with Enrichments

For best results, combine matrix execution with automatic enrichments:

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": ["NOSIS"],
    "checks": ["COMPLY_ADVANTAGE", "REPET"]
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}

Execution Flow:

Person entity created
NOSIS enrichment fetches identity & credit data
REPET checks watchlists
ComplyAdvantage screens for sanctions & PEP status
Risk matrix rules evaluate all collected data
Final risk score calculated
Compliance alerts generated if rules trigger

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:

Get Person Details - Retrieve complete person information
List Persons - Query your persons
Update Person - Modify person data
Create KYC Validation - Start KYC verification process

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

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

Person Entity Data Structure

Risk Matrix Execution

How It Works

Example with Risk Matrix

Combined with Enrichments

Response

Example Request

Response Example

Error Responses

400 Bad Request - Invalid Tax ID

400 Bad Request - Missing Required Fields

409 Conflict - Duplicate Entity

401 Unauthorized

Next Steps

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

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

​Person Entity Data Structure

​Risk Matrix Execution

​How It Works

​Example with Risk Matrix

​Combined with Enrichments

​Response

​Example Request

​Response Example

​Error Responses

​400 Bad Request - Invalid Tax ID

​400 Bad Request - Missing Required Fields

​409 Conflict - Duplicate Entity

​401 Unauthorized

​Next Steps

Overview

Endpoint

Authentication

Request Body

Person Entity Data Structure

Risk Matrix Execution

How It Works

Example with Risk Matrix

Combined with Enrichments

Response

Example Request

Response Example

Error Responses

400 Bad Request - Invalid Tax ID

400 Bad Request - Missing Required Fields

409 Conflict - Duplicate Entity

401 Unauthorized

Next Steps