Create an entity (person or company)

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>",
  "email": {},
  "phone": {},
  "operationalHours": {},
  "nationality": {},
  "registrationDate": {},
  "attributes": {},
  "riskFactors": {},
  "entityData": {},
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "shareholderDepth": 123,
  "relationships": [
    {}
  ],
  "status": "<string>",
  "monitoring": {},
  "autoExecuteIntegrations": {}
}
'

import requests

url = "http://api.gu1.ai/entities"

payload = {
    "type": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "countryCode": "<string>",
    "taxId": "<string>",
    "email": {},
    "phone": {},
    "operationalHours": {},
    "nationality": {},
    "registrationDate": {},
    "attributes": {},
    "riskFactors": {},
    "entityData": {},
    "isClient": True,
    "riskMatrixId": ["<string>"],
    "riskMatrixIds": ["<string>"],
    "skipRulesExecution": True,
    "shareholderDepth": 123,
    "relationships": [{}],
    "status": "<string>",
    "monitoring": {},
    "autoExecuteIntegrations": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    externalId: '<string>',
    name: '<string>',
    countryCode: '<string>',
    taxId: '<string>',
    email: {},
    phone: {},
    operationalHours: {},
    nationality: {},
    registrationDate: {},
    attributes: {},
    riskFactors: {},
    entityData: {},
    isClient: true,
    riskMatrixId: ['<string>'],
    riskMatrixIds: ['<string>'],
    skipRulesExecution: true,
    shareholderDepth: 123,
    relationships: [{}],
    status: '<string>',
    monitoring: {},
    autoExecuteIntegrations: {}
  })
};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'externalId' => '<string>',
    'name' => '<string>',
    'countryCode' => '<string>',
    'taxId' => '<string>',
    'email' => [
        
    ],
    'phone' => [
        
    ],
    'operationalHours' => [
        
    ],
    'nationality' => [
        
    ],
    'registrationDate' => [
        
    ],
    'attributes' => [
        
    ],
    'riskFactors' => [
        
    ],
    'entityData' => [
        
    ],
    'isClient' => true,
    'riskMatrixId' => [
        '<string>'
    ],
    'riskMatrixIds' => [
        '<string>'
    ],
    'skipRulesExecution' => true,
    'shareholderDepth' => 123,
    'relationships' => [
        [
                
        ]
    ],
    'status' => '<string>',
    'monitoring' => [
        
    ],
    'autoExecuteIntegrations' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"email\": {},\n  \"phone\": {},\n  \"operationalHours\": {},\n  \"nationality\": {},\n  \"registrationDate\": {},\n  \"attributes\": {},\n  \"riskFactors\": {},\n  \"entityData\": {},\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"shareholderDepth\": 123,\n  \"relationships\": [\n    {}\n  ],\n  \"status\": \"<string>\",\n  \"monitoring\": {},\n  \"autoExecuteIntegrations\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"email\": {},\n  \"phone\": {},\n  \"operationalHours\": {},\n  \"nationality\": {},\n  \"registrationDate\": {},\n  \"attributes\": {},\n  \"riskFactors\": {},\n  \"entityData\": {},\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"shareholderDepth\": 123,\n  \"relationships\": [\n    {}\n  ],\n  \"status\": \"<string>\",\n  \"monitoring\": {},\n  \"autoExecuteIntegrations\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"email\": {},\n  \"phone\": {},\n  \"operationalHours\": {},\n  \"nationality\": {},\n  \"registrationDate\": {},\n  \"attributes\": {},\n  \"riskFactors\": {},\n  \"entityData\": {},\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"shareholderDepth\": 123,\n  \"relationships\": [\n    {}\n  ],\n  \"status\": \"<string>\",\n  \"monitoring\": {},\n  \"autoExecuteIntegrations\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "errors": {},
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

Create an entity (person or company)

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>",
  "email": {},
  "phone": {},
  "operationalHours": {},
  "nationality": {},
  "registrationDate": {},
  "attributes": {},
  "riskFactors": {},
  "entityData": {},
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "shareholderDepth": 123,
  "relationships": [
    {}
  ],
  "status": "<string>",
  "monitoring": {},
  "autoExecuteIntegrations": {}
}
'

import requests

url = "http://api.gu1.ai/entities"

payload = {
    "type": "<string>",
    "externalId": "<string>",
    "name": "<string>",
    "countryCode": "<string>",
    "taxId": "<string>",
    "email": {},
    "phone": {},
    "operationalHours": {},
    "nationality": {},
    "registrationDate": {},
    "attributes": {},
    "riskFactors": {},
    "entityData": {},
    "isClient": True,
    "riskMatrixId": ["<string>"],
    "riskMatrixIds": ["<string>"],
    "skipRulesExecution": True,
    "shareholderDepth": 123,
    "relationships": [{}],
    "status": "<string>",
    "monitoring": {},
    "autoExecuteIntegrations": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    type: '<string>',
    externalId: '<string>',
    name: '<string>',
    countryCode: '<string>',
    taxId: '<string>',
    email: {},
    phone: {},
    operationalHours: {},
    nationality: {},
    registrationDate: {},
    attributes: {},
    riskFactors: {},
    entityData: {},
    isClient: true,
    riskMatrixId: ['<string>'],
    riskMatrixIds: ['<string>'],
    skipRulesExecution: true,
    shareholderDepth: 123,
    relationships: [{}],
    status: '<string>',
    monitoring: {},
    autoExecuteIntegrations: {}
  })
};

fetch('http://api.gu1.ai/entities', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'type' => '<string>',
    'externalId' => '<string>',
    'name' => '<string>',
    'countryCode' => '<string>',
    'taxId' => '<string>',
    'email' => [
        
    ],
    'phone' => [
        
    ],
    'operationalHours' => [
        
    ],
    'nationality' => [
        
    ],
    'registrationDate' => [
        
    ],
    'attributes' => [
        
    ],
    'riskFactors' => [
        
    ],
    'entityData' => [
        
    ],
    'isClient' => true,
    'riskMatrixId' => [
        '<string>'
    ],
    'riskMatrixIds' => [
        '<string>'
    ],
    'skipRulesExecution' => true,
    'shareholderDepth' => 123,
    'relationships' => [
        [
                
        ]
    ],
    'status' => '<string>',
    'monitoring' => [
        
    ],
    'autoExecuteIntegrations' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities"

	payload := strings.NewReader("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"email\": {},\n  \"phone\": {},\n  \"operationalHours\": {},\n  \"nationality\": {},\n  \"registrationDate\": {},\n  \"attributes\": {},\n  \"riskFactors\": {},\n  \"entityData\": {},\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"shareholderDepth\": 123,\n  \"relationships\": [\n    {}\n  ],\n  \"status\": \"<string>\",\n  \"monitoring\": {},\n  \"autoExecuteIntegrations\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"email\": {},\n  \"phone\": {},\n  \"operationalHours\": {},\n  \"nationality\": {},\n  \"registrationDate\": {},\n  \"attributes\": {},\n  \"riskFactors\": {},\n  \"entityData\": {},\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"shareholderDepth\": 123,\n  \"relationships\": [\n    {}\n  ],\n  \"status\": \"<string>\",\n  \"monitoring\": {},\n  \"autoExecuteIntegrations\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"type\": \"<string>\",\n  \"externalId\": \"<string>\",\n  \"name\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"email\": {},\n  \"phone\": {},\n  \"operationalHours\": {},\n  \"nationality\": {},\n  \"registrationDate\": {},\n  \"attributes\": {},\n  \"riskFactors\": {},\n  \"entityData\": {},\n  \"isClient\": true,\n  \"riskMatrixId\": [\n    \"<string>\"\n  ],\n  \"riskMatrixIds\": [\n    \"<string>\"\n  ],\n  \"skipRulesExecution\": true,\n  \"shareholderDepth\": 123,\n  \"relationships\": [\n    {}\n  ],\n  \"status\": \"<string>\",\n  \"monitoring\": {},\n  \"autoExecuteIntegrations\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "errors": {},
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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

string

required

The type of entity to create. Available types:

person - Individual person/customer
company - Business entity

string

Your unique identifier for this entity in your system. Optional — gu1 assigns one automatically when omitted (see table below).

string

required

Display name for the entity

string

required

ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)

string

Tax identification number (validated based on country). Within an organization, an active normalized taxId may belong to only one entity (person or company). Conflicts return 409 with code DUPLICATE_TAX_ID.

When externalId is omitted

You send	Stored `externalId`
`taxId` (with or without formatting)	Normalized tax ID: letters and digits only, uppercase — no dots, dashes, or spaces. Example: `30-12345678-9` → `30123456789`
No `taxId`	`{name-slug}-{timestamp-ms}` derived from `name` (lowercase, non-alphanumeric → `-`, max 20 chars). Example: `acme-corp-1719345678901`

The taxId column is still saved in the country display format when you provide a tax ID. Send an explicit externalId when you need your own CRM or user ID independent of the tax document.

string | null

Optional primary contact email stored on the entity row (nullable). Existing entities keep null until set. Send null on PATCH to clear.

string | null

Optional primary contact phone stored on the entity row (nullable). Existing entities keep null until set. Send null on PATCH to clear.

object | null

Optional weekly operational hours for KYT rules (outside_entity_operational_hours). Root-level field (not inside attributes).

timezone (required when operationalHours is sent): must be one of the transaction_time_zone enum values. Full list: Transaction Time Zone Enum.
weekly: keys monday … sunday. Each day: { "start": "09:00", "end": "18:00" } or { "closed": true }. Omitted days are treated as closed.
Used by transaction rules that compare transactedAt to this schedule in the entity’s local timezone.

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.

string | number | Date

Registration or incorporation date of the entity. Accepts:

ISO 8601 datetime string (e.g., “2020-06-15T00:00:00Z”)
Unix timestamp (number)
JavaScript Date object

object

Optional — Custom attributes. Accepts flat ({ "phone": "..." }) or category-nested ({ "contact": { "phone": "..." } }) input. Stored verbatim (nested objects act as categories, returned as sent); see Update entity for details.

object

Optional - Custom risk factors and manual risk score overridesProperties:

reasons (array of strings) - Reasons for the risk assessment
customLabel (object) - Custom risk label configuration:
- name (string) - Label name (e.g., “High Risk”, “Suspicious”)
- color (string) - Color code for UI display
- status (string) - Status indicator
- minScore (number) - Minimum score for this label
- maxScore (number | null) - Maximum score (null for infinite)
- severity (enum) - Severity level: ‘low’, ‘medium’, ‘high’, ‘critical’
displayRange (object) - Score range display configuration:
- max (number | null) - Maximum value (null for infinite)
- min (number) - Minimum value
- current (number) - Current score value
- isInfinite (boolean) - Whether the range is infinite
originalScore (number) - Original calculated score before manual override
normalizedScore (number) - Normalized score value

Use case: Override automatic risk scoring with manual assessments for special cases.

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

boolean

default:"false"

Mark this entity as a client/customer for tracking purposes

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.

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.

boolean

default:"false"

Skip automatic rules execution after entity creation

number

default:"0"

For company entities: How many levels of shareholders to auto-create (0-5).

0 = None (default)
1 = Direct shareholders only
2 = Shareholders + their shareholders
3-5 = Deeper nested levels

Useful for automatic KYB and UBO (Ultimate Beneficial Owner) discovery.

array

Declarative links to entities that already exist in the same organization (max 10). Independent of shareholderDepth / enrichment.Each item must include exactly one of: relatedEntityId (UUID), relatedTaxId, relatedExternalId.

Field	Description
`relationshipType`	Graph enum (`shareholder`, `manages`, `owns`, `employed_by`, …)
`role` / `roles`	Role(s) stored in `metadata.roles` (e.g. `SOCIO`, `REPRESENTANTE`)
`relatedCountryCode`	Optional ISO2 to normalize `relatedTaxId` (default: new entity `countryCode`)
`asSource`	Default `true`: the created entity is source and the related entity is target. With `shareholder`, the created entity is a shareholder of the counterpart (e.g. person → company). `false` reverses the direction.

If the counterpart is missing → 404 RELATED_ENTITY_NOT_FOUND and the entity is not created.

string

default:"under_review"

Initial status for the entity. Options:

active - Entity is active
inactive - Entity is inactive
not_started - Analysis not started yet (optional initial state; default remains under_review)
blocked - Entity is blocked
under_review - Entity is under review (default)
pending_verification - Awaiting KYC/KYB completion
awaiting_information - Waiting on client data (e.g. onboarding documents requested by email)
suspended - Entity is suspended
expired - Entity has expired
deleted - Soft deleted
rejected - Entity was rejected

object

Optional. Requests watchlist mode (op 1: screening plus watchlist subscription for periodic runs) for a monitoring-capable enrichment, instead of a one-off check (op 0).Scope today: only global_gueno_sanctions_enrichment. Map keys must match codes in autoExecuteIntegrations.enrichments. Legacy *_check codes were removed (2026-06-04) and are no longer part of the contract.

main: flags for the main entity on this POST /entities.
relationships: ignored here; use Create automatically with depth > 0.

Per-code value (object recommended; legacy boolean still accepted):

{ "watchlist": true } — subscribe; monitoring rules use the entity’s global riskMatrixId.
{ "watchlist": true, "riskMatrixId": "<uuid>" } — subscribe; only that matrix on monitoring-triggered runs.
{ "watchlist": false } or false — no watchlist.
true — same as { "watchlist": true }.

Requirements (if any fail, enrichment still runs as op 0): (1) code in enrichments or active via execute-all; (2) org monitoring ON in Marketplace for Gu1 sanctions.Guide: Gu1 sanctions monitoring. Examples: Monitoring on create.

object

Configure automatic execution of enrichment integrations when creating the entity.Properties:

executeAllActiveEnrichments (boolean) - Execute all active enrichment integrations
enrichments (array) - Array of specific enrichment provider codes to execute (see Provider Codes Reference)
enrichmentGroupRefs (array of strings, optional) - Marketplace enrichment group slugs. 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.
excludeEnrichments (array, optional, default: []) - Provider codes to omit from the final resolved enrichment set

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",
    "gender": "M | F | male | female | unknown | other",
    "phone": "string",
    "alternativePhone": "string",
    "idType": "national_id | passport | drivers_license | tax_id | other",
    "idNumber": "string",
    "isPep": boolean,
    "pepPosition": "string",
    "pepCountry": "string"
  }
}

Gender (entityData.person.gender) — closed enum. Only the values below are accepted; any other string (e.g. X, non_binary) returns a validation error.

Value	Meaning
`M` or `male`	Male
`F` or `female`	Female
`other`	Other / non-binary — use this code for non-binary identity
`unknown`	Not provided or unknown

Argentina (AR): automatic CUIL derivation from DNI + gender and RENAPER identity checks only recognize M/F (or male/female). With other or unknown, CUIL is not auto-derived and RENAPER cannot use gender from the entity.

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

Query Parameters

boolean

default:"false"

Force re-enrichment of the entity even if it already exists in the system.Type: boolean (query string: "true" or "false")Behavior:

When true: Forces the system to fetch fresh data from enrichment providers (e.g., background checks, KYC data, company registries)
When false or omitted: Uses cached enrichment data if available
Overrides organization setting enrichmentsConfig.reEnrichExistingEntities

Use Cases:

Re-validating entity data after a significant time period
Updating information when you know external data has changed
Manual refresh triggered by compliance team
Periodic data quality audits

Example:

POST http://api.gu1.ai/entities?refresh=true

Note: Re-enrichment may incur additional costs from third-party data providers.

Response

boolean

Indicates if the entity was created successfully

object

Present when an enrichment listed in autoExecuteIntegrations did not run or failed. The entity is still created (success: true). enrichmentFailed[].failedProviders has providerCode, code, and error (English). code is INTEGRATION_NOT_ENABLED when the organization has not enabled that enrichment, plus INTEGRATION_NOT_CONFIGURED, INTEGRATION_BLOCKED, INTEGRATION_GLOBALLY_DISABLED, CONTRACT_ACCESS_NOT_INCLUDED, INTEGRATION_NOT_FOUND, and INTEGRATION_NOT_APPLICABLE (country or entity type). Those configuration codes are not retried.

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

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.

object

At the root of the response (same as transactions API). Only present when rules ran (e.g. skipRulesExecution is false and rules engine executed). Same value as rulesResult.rulesExecutionSummary. 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 (array of { name?, type?, severity?, description? }), 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: Gu1 Sanctions Monitoring on Create

monitoring does not run integrations by itself — it only changes how an enrichment already listed in autoExecuteIntegrations runs. Today the documented case is global_gueno_sanctions_enrichment (org must allow monitoring in Marketplace).

Condition	Effect
Code in `enrichments` + `monitoring.main[code]` with watchlist on + org monitoring ON	Op 1 — screening plus watchlist / daily screening.
No `monitoring` or `watchlist: false`	Op 0 — one-off screening only.
`monitoring` set but org monitoring OFF	Op 0 — no mandatory error; screening still runs.
`monitoring` without the code in `enrichments`	No effect.

Legacy *_check codes (e.g. global_gueno_sanctions_check) were removed (2026-06-04). For watchlist on create, use global_gueno_sanctions_enrichment in both enrichments and monitoring.main.

Watchlist Only (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": {
        "watchlist": true
      }
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"]
  }
}

Local Enrichments + Gu1 Monitoring (AR Person)

Combine registry/KYC enrichments with Gu1 watchlist in one POST /entities. monitoring only affects keys present in the map.

{
  "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"
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_renaper_data_enrichment",
      "ar_repet_person_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  }
}

ar_renaper_* and ar_repet_* run as normal enrichments; only global_gueno_sanctions_enrichment can use op 1 when org monitoring is enabled.

Dedicated Risk Matrix for Monitoring (Optional)

"monitoring": {
  "main": {
    "global_gueno_sanctions_enrichment": {
      "watchlist": true,
      "riskMatrixId": "660e8400-e29b-41d4-a716-446655440001"
    }
  }
}

riskMatrixId: null means inherit the entity global matrix for monitoring runs.

Company (`type: "company"`)

Same monitoring.main shape; adjust type, entityData.company, and enrichments for your country.

{
  "type": "company",
  "externalId": "co_screening_001",
  "name": "Tech Solutions S.A.",
  "countryCode": "AR",
  "taxId": "30-71000001-2",
  "entityData": {
    "company": {
      "legalName": "Tech Solutions S.A.",
      "tradeName": "Tech Solutions",
      "industry": "Software"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": { "watchlist": true }
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": ["global_gueno_sanctions_enrichment"]
  }
}

monitoring.relationships is not used on POST /entities. For shareholders or related entities in the same job, use Create automatically with depth > 0, monitoring.relationships, and matching codes in autoExecuteIntegrationsShareholders.

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

const response = await fetch('http://api.gu1.ai/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
    }
  })
});

const data = await response.json();
console.log(data.entity);

import requests

response = requests.post(
    'http://api.gu1.ai/entities',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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'
        }
    }
)

entity = response.json()['entity']
print(entity)

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

const response = await fetch('http://api.gu1.ai/entities', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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'
    }
  })
});

const data = await response.json();
console.log(data.entity);

import requests

response = requests.post(
    'http://api.gu1.ai/entities',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        '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'
        }
    }
)

entity = response.json()['entity']
print(entity)

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
}

Duplicate tax ID (same organization, any entity type) returns DUPLICATE_TAX_ID with existingEntityId / existingEntityType in details when available.

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. Try again in 60 minutes.",
  "retryAfter": 3600,
  "retryAfterMinutes": 60,
  "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

​Entity Data Structures

​Person Entity

​Company Entity

​Device Entity

​Payment Method Entity

​Location Entity

​Document Entity

​Alert Entity

​Query Parameters

​Response

​Example: Gu1 Sanctions Monitoring on Create

​Watchlist Only (Person)

​Local Enrichments + Gu1 Monitoring (AR Person)

​Dedicated Risk Matrix for Monitoring (Optional)

​Company (type: "company")

​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

Query Parameters

Response

Example: Gu1 Sanctions Monitoring on Create

Watchlist Only (Person)

Local Enrichments + Gu1 Monitoring (AR Person)

Dedicated Risk Matrix for Monitoring (Optional)

Company (`type: "company"`)

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