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,
"relationships": [
{}
]
}
'import requests
url = "http://api.gu1.ai/entities"
payload = {
"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,
"relationships": [{}]
}
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: {},
monitoring: {},
autoExecuteIntegrations: {},
attributes: {},
entityData: {},
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
shareholderDepth: 123,
relationships: [{}]
})
};
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' => [
],
'monitoring' => [
],
'autoExecuteIntegrations' => [
],
'attributes' => [
],
'entityData' => [
],
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'shareholderDepth' => 123,
'relationships' => [
[
]
]
]),
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 \"monitoring\": {},\n \"autoExecuteIntegrations\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"shareholderDepth\": 123,\n \"relationships\": [\n {}\n ]\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 \"monitoring\": {},\n \"autoExecuteIntegrations\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"shareholderDepth\": 123,\n \"relationships\": [\n {}\n ]\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 \"monitoring\": {},\n \"autoExecuteIntegrations\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"shareholderDepth\": 123,\n \"relationships\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"entity": {},
"rulesResult": {},
"rulesExecutionSummary": {}
}Criar uma entidade (pessoa ou empresa)
Crie uma nova pessoa ou empresa com dados personalizados — no modelo universal de entidades gu1 para KYC, KYB e análise de risco, com exemplos para create.
POST
/
entities
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,
"relationships": [
{}
]
}
'import requests
url = "http://api.gu1.ai/entities"
payload = {
"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,
"relationships": [{}]
}
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: {},
monitoring: {},
autoExecuteIntegrations: {},
attributes: {},
entityData: {},
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
shareholderDepth: 123,
relationships: [{}]
})
};
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' => [
],
'monitoring' => [
],
'autoExecuteIntegrations' => [
],
'attributes' => [
],
'entityData' => [
],
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'shareholderDepth' => 123,
'relationships' => [
[
]
]
]),
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 \"monitoring\": {},\n \"autoExecuteIntegrations\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"shareholderDepth\": 123,\n \"relationships\": [\n {}\n ]\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 \"monitoring\": {},\n \"autoExecuteIntegrations\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"shareholderDepth\": 123,\n \"relationships\": [\n {}\n ]\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 \"monitoring\": {},\n \"autoExecuteIntegrations\": {},\n \"attributes\": {},\n \"entityData\": {},\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"shareholderDepth\": 123,\n \"relationships\": [\n {}\n ]\n}"
response = http.request(request)
puts response.read_body{
"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
string
required
O tipo de entidade a ser criada. Tipos disponíveis:
person- Pessoa física/clientecompany- Entidade empresarial
string
Seu identificador único para esta entidade em seu sistema. Opcional — a gu1 atribui um automaticamente se omitido (ver tabela abaixo).
string
required
Nome de exibição para a entidade
string
required
Código de país ISO 3166-1 alpha-2 (ex: “US”, “BR”, “AR”)
string
Número de identificação fiscal (validado com base no país). Em uma organização, um
taxId ativo normalizado pode pertencer a apenas uma entidade (person ou company). Conflitos retornam 409 com código DUPLICATE_TAX_ID.Quando
A coluna
externalId é omitido| Você envia | externalId armazenado |
|---|---|
taxId (com ou sem formatação) | Tax ID normalizado: apenas letras e dígitos, maiúsculas — sem pontos, traços ou espaços. Exemplo: 30-12345678-9 → 30123456789 |
Sem taxId | {slug-nome}-{timestamp-ms} derivado de name (minúsculas, não alfanumérico → -, máx. 20 caracteres). Exemplo: acme-corp-1719345678901 |
taxId continua salva no formato de exibição do país quando informada. Envie um externalId explícito se precisar do seu próprio ID de CRM ou usuário, independente do documento fiscal.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.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.object | null
Horário operativo opcional para regras KYT (
outside_entity_operational_hours). Campo na raiz (não em attributes).timezone(obrigatório seoperationalHoursfor enviado): valor do enum transaction_time_zone (mesmo detransaction.timeZone). Lista completa: Enum fuso horário.weekly: chavesmonday…sunday. Cada dia:{ "start": "09:00", "end": "18:00" }ou{ "closed": true }. Dias omitidos = fechado.
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.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 nestePOST /entities.relationships: ignorado aqui; use Criar automaticamente comdepth> 0.
boolean legacy ainda aceito):{ "watchlist": true }— inscrição; matriz de monitoramento = herdarriskMatrixIdda entidade.{ "watchlist": true, "riskMatrixId": "<uuid>" }— inscrição; somente essa matriz em regras/screening de monitoramento.{ "watchlist": false }oufalse— sem watchlist.true— equivalente a{ "watchlist": true }.
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.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). ComexecuteAllActiveEnrichments: false, são resolvidos e mesclados comenrichmentsexplícitos. ComexecuteAllActiveEnrichments: true, os refs de grupo são ignorados;enrichmentsexplícitos ainda podem acrescentar códigos após o conjunto ativo.
object
Opcional — Atributos personalizados. Aceita formato plano (
{ "phone": "..." }) ou aninhado por categoria ({ "contact": { "phone": "..." } }). Armazenados exatamente como enviados (objetos aninhados atuam como categorias e são retornados como enviados); ver Atualizar entidade para detalhes.object
Opcional - Estrutura de dados específica do tipo. Veja exemplos abaixo para cada tipo de entidade.
Quando usar entityData?Exemplo Completo (Person com dados KYC):
- Opcional para criação básica de entidade - Você pode criar uma entidade apenas com
type,name,taxIdecountryCode - 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
{
"type": "person",
"name": "João Silva",
"taxId": "12345678900",
"countryCode": "BR"
// entityData não é necessário para criação básica
}
{
"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
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.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.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.
number
default:"0"
Apenas entidades company: níveis de acionistas a criar automaticamente (0–5).
0 = nenhum (padrão).array
Vínculos declarativos a entidades já existentes na mesma organização (máx. 10). Independente de
Se a contraparte não existir → 404
shareholderDepth / enrichment.Cada item deve incluir exatamente um de: relatedEntityId (UUID), relatedTaxId, relatedExternalId.| Campo | Descrição |
|---|---|
relationshipType | Enum do grafo (shareholder, manages, owns, employed_by, …) |
role / roles | Papel(éis) em metadata.roles (ex. SOCIO, REPRESENTANTE) |
relatedCountryCode | ISO2 opcional para normalizar relatedTaxId (padrão: countryCode da nova entidade) |
asSource | Padrão true: a entidade criada é source e a relacionada é target. Com shareholder, a criada é acionista/sócia da contraparte (ex. pessoa → empresa). false inverte a direção. |
RELATED_ENTITY_NOT_FOUND e a entidade não é criada.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 (
Argentina (AR): a derivação automática de CUIL a partir de DNI + gênero e as checagens RENAPER reconhecem somente
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 |
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
boolean
default:"false"
Força o re-enriquecimento da entidade mesmo que já exista no sistema.Tipo: Nota: O re-enriquecimento pode incorrer em custos adicionais de provedores de dados externos.
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
falseou omitido: Utiliza dados de enriquecimento em cache se disponíveis - Sobrescreve a configuração da organização
enrichmentsConfig.reEnrichExistingEntities
- 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
POST http://api.gu1.ai/entities?refresh=true
Resposta
boolean
Indica se a entidade foi criada com sucesso
object
O objeto de entidade criado incluindo:
id- ID interno do gu1externalId- Seu ID externoorganizationId- ID da sua organizaçãotype- Tipo de entidadename- Nome da entidaderiskScore- Pontuação de risco inicial (0-100)status- Status da entidadeentityData- Dados específicos do tipoattributes- Atributos personalizadoscreatedAt- Data/hora de criaçãoupdatedAt- Data/hora da última atualização
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.
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âmetromonitoring 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 doriskMatrixId 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"
}
}'
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)
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"
}
}'
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)
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
}
DUPLICATE_TAX_ID com existingEntityId / existingEntityType em details quando disponíveis.
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": "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
Was this page helpful?