Criar uma entidade (pessoa ou empresa)

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": {},
  "monitoring": {},
  "autoExecuteIntegrations": {},
  "attributes": {},
  "entityData": {},
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "shareholderDepth": 123
}
'

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

POST

entities

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": {},
  "monitoring": {},
  "autoExecuteIntegrations": {},
  "attributes": {},
  "entityData": {},
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "shareholderDepth": 123
}
'

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

Visão Geral

Cria uma nova entidade com o tipo e atributos especificados. Entidades representam os objetos de dados principais que você deseja analisar para risco e conformidade.

Endpoint

POST http://api.gu1.ai/entities

Autenticação

Requer uma chave de API válida no cabeçalho Authorization:

Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

type

string

required

O tipo de entidade a ser criada. Tipos disponíveis:

person - Pessoa física/cliente
company - Entidade empresarial

externalId

string

required

Seu identificador único para esta entidade em seu sistema

name

string

required

Nome de exibição para a entidade

countryCode

string

required

Código de país ISO 3166-1 alpha-2 (ex: “US”, “BR”, “AR”)

taxId

string

Número de identificação fiscal (validado com base no país)

string | null

E-mail de contato principal na linha da entidade (opcional, nullable). Entidades existentes permanecem null até ser definido. Em PATCH, null limpa o campo.

phone

string | null

Telefone de contato principal na linha da entidade (opcional, nullable). Entidades existentes permanecem null até ser definido. Em PATCH, null limpa o campo.

operationalHours

object | null

Horário operativo opcional para regras KYT (outside_entity_operational_hours). Campo na raiz (não em attributes).

timezone (obrigatório se operationalHours for enviado): valor do enum transaction_time_zone (mesmo de transaction.timeZone). Lista completa: Enum fuso horário.
weekly: chaves monday … sunday. Cada dia: { "start": "09:00", "end": "18:00" } ou { "closed": true }. Dias omitidos = fechado.

nationality

string | null

Nacionalidade opcional na raiz: ISO 3166-1 alpha-2 ou um rótulo reconhecido que a API mapeia para ISO2. Se omitido, o campo na raiz pode ser derivado de entityData.person.nationality ou entityData.company.nationality quando mapeável.

monitoring

object

Opcional. Pede que um enriquecimento com suporte a monitoramento rode em modo watchlist (op 1: screening + inscrição para corridas periódicas), não só consulta pontual (op 0).Escopo hoje: apenas global_gueno_sanctions_enrichment. A chave do mapa é o mesmo código em autoExecuteIntegrations.enrichments. Códigos legacy *_check foram removidos (2026-06-04) e não fazem mais parte do contrato.

main: flags da entidade principal neste POST /entities.
relationships: ignorado aqui; use Criar automaticamente com depth > 0.

Valor por código (objeto recomendado; boolean legacy ainda aceito):

{ "watchlist": true } — inscrição; matriz de monitoramento = herdar riskMatrixId da entidade.
{ "watchlist": true, "riskMatrixId": "<uuid>" } — inscrição; somente essa matriz em regras/screening de monitoramento.
{ "watchlist": false } ou false — sem watchlist.
true — equivalente a { "watchlist": true }.

Requisitos (se faltar algum, o enrichment roda como op 0): (1) código em enrichments ou ativo via execute-all; (2) monitoramento ON no Marketplace para Gu1 sanções.Guia: Monitoramento de sanções Gu1. Exemplos: Monitoramento na criação.

autoExecuteIntegrations

object

Opcional — Executar integrações (enriquecimentos e checks) logo após criar a entidade.Propriedades:

executeAllActiveEnrichments (boolean)
enrichments (array de códigos de provedor; ver códigos de provedor)
enrichmentGroupRefs (array de strings, opcional) — Slugs de grupos de enriquecimento do Marketplace (somente enriquecimentos). Com executeAllActiveEnrichments: false, são resolvidos e mesclados com enrichments explícitos. Com executeAllActiveEnrichments: true, os refs de grupo são ignorados; enrichments explícitos ainda podem acrescentar códigos após o conjunto ativo.

attributes

object

Opcional - Atributos personalizados como pares chave-valor para metadados flexíveisUse isto para campos personalizados que não se encaixam no esquema padrão (ex: IDs internos, tags, flags)

entityData

object

Opcional - Estrutura de dados específica do tipo. Veja exemplos abaixo para cada tipo de entidade.

Quando usar entityData?

Opcional para criação básica de entidade - Você pode criar uma entidade apenas com type, name, taxId e countryCode
Necessário para enriquecimento e análise de risco - Se você quiser executar verificações de conformidade, precisará fornecer campos relevantes
Pode ser preenchido depois - Você pode criar uma entidade mínima primeiro, depois atualizá-la com dados completos antes de executar a análise de risco

Exemplo Mínimo (Person):

{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678900",
  "countryCode": "BR"
  // entityData não é necessário para criação básica
}

Exemplo Completo (Person com dados KYC):

{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678900",
  "countryCode": "BR",
  "entityData": {
    "person": {
      "firstName": "João",
      "lastName": "Silva",
      "dateOfBirth": "1980-01-15",
      "email": "joao@example.com",
      "phone": "+5511912345678"
    }
  }
}

Matriz de risco e execução de regras

riskMatrixId

string | string[]

Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Se informados, após a criação o sistema avalia a entidade somente contra regras ativas dessas matrizes (salvo skipRulesExecution: true). Mesma semântica que riskMatrixIds quando você envia um único id como string.

riskMatrixIds

string[]

Forma preferida para várias matrizes: lista ordenada de UUIDs da sua organização. Quando presente e não vazia, tem precedência sobre riskMatrixId.

skipRulesExecution

boolean

default:"false"

Pular a execução automática de regras após criar a entidade. Use para criar primeiro e disparar regras manualmente depois.

shareholderDepth

number

default:"0"

Apenas entidades company: níveis de acionistas a criar automaticamente (0–5). 0 = nenhum (padrão).

Estruturas de Dados de Entidade

Entidade Person

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number,
    "incomeCurrency": "string",
    "address": "string | object (ver nota Formato de endereço)",
    "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"
  }
}

Gênero (entityData.person.gender) — enum fechado. Apenas os valores da tabela são aceitos; qualquer outra string (ex.: X, non_binary) retorna erro de validação.

Valor	Significado
`M` ou `male`	Masculino
`F` ou `female`	Feminino
`other`	Outro / não binário — use este código para identidade não binária
`unknown`	Não informado ou desconhecido

Argentina (AR): a derivação automática de CUIL a partir de DNI + gênero e as checagens RENAPER reconhecem somente M/F (ou male/female). Com other ou unknown, o CUIL não é derivado automaticamente e o RENAPER não usa o gênero da entidade.

Entidade Company

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "industry": "string",
    "employeeCount": number,
    "revenue": number
  }
}

Entidade Alert

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

Parâmetros de Query

refresh

boolean

default:"false"

Força o re-enriquecimento da entidade mesmo que já exista no sistema.Tipo: boolean (query string: "true" ou "false")Comportamento:

Quando true: Força o sistema a buscar dados atualizados de provedores de enriquecimento (ex: verificação de antecedentes, dados KYC, registros de empresas)
Quando false ou omitido: Utiliza dados de enriquecimento em cache se disponíveis
Sobrescreve a configuração da organização enrichmentsConfig.reEnrichExistingEntities

Casos de Uso:

Re-validar dados da entidade após um período de tempo significativo
Atualizar informações quando se sabe que os dados externos mudaram
Atualização manual acionada pela equipe de compliance
Auditorias periódicas de qualidade de dados

Exemplo:

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

Nota: O re-enriquecimento pode incorrer em custos adicionais de provedores de dados externos.

Resposta

success

boolean

Indica se a entidade foi criada com sucesso

entity

object

O objeto de entidade criado incluindo:

id - ID interno do gu1
externalId - Seu ID externo
organizationId - ID da sua organização
type - Tipo de entidade
name - Nome da entidade
riskScore - Pontuação de risco inicial (0-100)
status - Status da entidade
entityData - Dados específicos do tipo
attributes - Atributos personalizados
createdAt - Data/hora de criação
updatedAt - Data/hora da última atualização

rulesResult

object

Resultado da execução de regras (apenas presente quando as regras foram executadas, ex. quando skipRulesExecution é false e há matriz de risco configurada), incluindo:

success (boolean) - Se as regras foram executadas com sucesso
rulesTriggered (number) - Número de regras disparadas
alerts (array) - Alertas gerados pelas regras
riskScore (number) - Pontuação de risco final
decision (string) - Decisão final (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
rulesExecutionSummary (object) - Presente quando as regras foram executadas. Ver abaixo a estrutura.

rulesExecutionSummary

object

Apenas presente quando as regras foram executadas (ex. skipRulesExecution é false). Resumo de quais regras deram match (hit) vs não (no hit), ações executadas e pontuação total. Omitido quando as regras não foram executadas.

rulesHit (array) - Regras cujas condições foram atendidas. Cada item: name, description, score, priority, category, status (ex. active, shadow), conditions (array de { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
rulesNoHit (array) - Regras avaliadas mas cujas condições não foram atendidas. Mesma estrutura que rulesHit (inclui ações configuradas, não executadas).
actionsExecuted (object) - Ações executadas agregadas de todas as regras que deram hit: alerts (array de { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, maior peso), status (status aplicado à entidade, se houver), assignedUser ({ userId }, se houver), customKeys (array de strings, opcional) — chaves de ações personalizadas das regras que deram match; para integrações/workflows.
totalScore (number) - Soma do score de todas as regras que deram hit e não estão em status shadow.

Exemplo: monitoramento de sanções Gu1 na criação

O parâmetro monitoring não executa integrações sozinho: só altera como roda um enrichment já listado em autoExecuteIntegrations. Hoje o caso documentado é global_gueno_sanctions_enrichment (monitoramento da org no Marketplace).

Condição	Efeito
Código em `enrichments` + `monitoring.main[código]` com watchlist ativo + monitoramento org ON	Op 1 — screening + watchlist / screening diário.
Sem `monitoring` ou `watchlist: false`	Op 0 — só consulta pontual.
`monitoring` com monitoramento org OFF	Op 0 — sem erro obrigatório; screening roda.
Só `monitoring` sem o código em `enrichments`	Sem efeito.

Códigos *_check (ex.: global_gueno_sanctions_check) foram removidos (2026-06-04). Para watchlist na criação, use global_gueno_sanctions_enrichment em enrichments e em monitoring.main.

Só watchlist Gu1 (pessoa)

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

Enriquecimentos locais + monitoramento Gu1 (pessoa AR)

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

Matriz de risco só para monitoramento (opcional)

Além do riskMatrixId na entidade (regras na criação), você pode fixar uma matriz diferente só para corridas disparadas pelo screening diário de monitoramento:

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

riskMatrixId: null no objeto equivale a herdar a matriz global da entidade nessas corridas de monitoramento.

Empresa (`type: "company"`)

{
  "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 não é usado em POST /entities. Para acionistas/relacionadas no mesmo job, use Criar automaticamente com depth > 0, monitoring.relationships e códigos em autoExecuteIntegrationsShareholders.

Exemplos

Criar Entidade Person (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"
    }
  }'

Criar Entidade Company (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"
    }
  }'

Exemplo de Resposta

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

Respostas de Erro

400 Bad Request - ID Fiscal Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Formato de CUIT inválido. Por favor verifique o formato e tente novamente.",
    "details": {
      "field": "taxId",
      "taxIdName": "CUIT",
      "providedValue": "20-12345678-9"
    }
  },
  "entity": null
}

400 Bad Request - Campos Obrigatórios Ausentes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Faltam campos obrigatórios para criação da empresa",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

409 Conflict - Entidade Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entidade com este external_id já existe",
    "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": "Você excedeu o limite de taxa da API. Por favor aguarde antes de fazer mais solicitações.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}

500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Ocorreu um erro inesperado ao criar a entidade",
    "details": {
      "message": "Database connection timeout"
    }
  },
  "entity": null
}

Próximos Passos

Após criar uma entidade, você pode:

Solicitar Análise de IA - Obter avaliação automatizada de risco
Listar Entidades - Consultar suas entidades
Obter Detalhes da Entidade - Recuperar informações completas da entidade
Aplicar Regras - Executar regras de conformidade e risco

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Matriz de risco e execução de regras

​Estruturas de Dados de Entidade

​Entidade Person

​Entidade Company

​Entidade Alert

​Parâmetros de Query

​Resposta

​Exemplo: monitoramento de sanções Gu1 na criação

​Só watchlist Gu1 (pessoa)

​Enriquecimentos locais + monitoramento Gu1 (pessoa AR)

​Matriz de risco só para monitoramento (opcional)

​Empresa (type: "company")

​Exemplos

​Criar Entidade Person (KYC)

​Criar Entidade Company (KYB)

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request - ID Fiscal Inválido

​400 Bad Request - Campos Obrigatórios Ausentes

​409 Conflict - Entidade Duplicada

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Matriz de risco e execução de regras

Estruturas de Dados de Entidade

Entidade Person

Entidade Company

Entidade Alert

Parâmetros de Query

Resposta

Exemplo: monitoramento de sanções Gu1 na criação

Só watchlist Gu1 (pessoa)

Enriquecimentos locais + monitoramento Gu1 (pessoa AR)

Matriz de risco só para monitoramento (opcional)

Empresa (`type: "company"`)

Exemplos

Criar Entidade Person (KYC)

Criar Entidade Company (KYB)

Exemplo de Resposta

Respostas de Erro

400 Bad Request - ID Fiscal Inválido

400 Bad Request - Campos Obrigatórios Ausentes

409 Conflict - Entidade Duplicada

401 Unauthorized

429 Too Many Requests

500 Internal Server Error

Próximos Passos