Skip to main content
POST
http://api.gu1.ai
/
entities
Criar
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>",
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {}
}
'
{
  "success": true,
  "entity": {}
}

​
VisĂŁo Geral

Cria uma nova entidade de pessoa com os atributos especificados. Entidades de pessoa representam clientes individuais que vocĂȘ deseja analisar para risco e conformidade (KYC).

​
Endpoint

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

​
Autenticação

Requer uma chave de API vålida no cabeçalho de autorização: 
Authorization: Bearer YOUR_API_KEY

​
Corpo da Requisição

​
type
string
required
Deve ser person para criar uma entidade de pessoa
​
externalId
string
required
Seu identificador Ășnico para esta pessoa em seu sistema
​
name
string
required
Nome de exibição da pessoa
​
countryCode
string
required
Código de país ISO 3166-1 alpha-2 (por exemplo, “US”, “BR”, “AR”)
​
taxId
string
NĂșmero de identificação fiscal (validado com base no paĂ­s)
📋 Ver Formatos de Tax ID por País para formatos aceitos e regras de validação para cada país.
​
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 da pessoa (veja abaixo)
Quando usar entityData?
  • Opcional para criação bĂĄsica de entidade - VocĂȘ pode criar uma pessoa com apenas 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 pessoa mĂ­nima primeiro, depois atualizĂĄ-la com dados completos antes de executar anĂĄlise de risco
Exemplo MĂ­nimo:
{
  "type": "person",
  "name": "JoĂŁo Silva",
  "taxId": "12345678901",
  "countryCode": "BR"
  // Não é necessårio entityData para criação båsica
}
Exemplo Completo (com dados KYC):
{
  "type": "person",
  "name": "JoĂŁo Silva",
  "taxId": "12345678901",
  "countryCode": "BR",
  "entityData": {
    "person": {
      "firstName": "JoĂŁo",
      "lastName": "Silva",
      "dateOfBirth": "1980-01-15",
      "email": "joao@example.com",
      "phone": "+5511987654321"
    }
  }
}
​
registrationDate
string
Data de registro da pessoa em formato ISO 8601 datetime (ex: “2024-01-15T10:30:00Z”)
​
isClient
boolean
default:"false"
Marcar esta pessoa como cliente para fins de rastreamento
​
riskMatrixId
string
UUID da matriz de risco para executar regras automaticamente. Veja a seção Execução de Matriz de Risco abaixo para mais detalhes.
​
skipRulesExecution
boolean
default:"false"
Pular a execução automåtica de regras após a criação da pessoa. Use isso para criar a entidade primeiro e acionar as regras manualmente depois.
​
status
string
default:"under_review"
Status inicial da pessoa. OpçÔes:
  • active - Pessoa estĂĄ ativa
  • inactive - Pessoa estĂĄ inativa
  • blocked - Pessoa estĂĄ bloqueada
  • under_review - Pessoa estĂĄ em revisĂŁo (padrĂŁo)
  • suspended - Pessoa estĂĄ suspensa
  • pending_verification - Verificação pendente
  • expired - Registro da pessoa expirou
  • deleted - ExcluĂ­do suavemente
  • rejected - Pessoa foi rejeitada
​
autoExecuteIntegrations
object
Configurar a execução automåtica de integraçÔes (enriquecimentos e verificaçÔes) ao criar a pessoa.Estrutura:
{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": ["NOSIS"],
  "checks": ["COMPLY_ADVANTAGE", "REPET"]
}
Propriedades:
  • executeAllActiveEnrichments (boolean) - Executar todas as integraçÔes de enriquecimento ativas configuradas na sua organização
  • executeAllActiveChecks (boolean) - Executar todas as integraçÔes de verificação ativas configuradas na sua organização
  • enrichments (string[]) - Array de cĂłdigos especĂ­ficos de provedores de enriquecimento para executar
  • checks (string[]) - Array de cĂłdigos especĂ­ficos de provedores de verificação para executar
CĂłdigos de Provedores Comuns:
  • NOSIS - NOSIS Argentina (dados de identidade e crĂ©dito de pessoas)
  • REPET - REPET Argentina (triagem de listas de vigilĂąncia)
  • COMPLY_ADVANTAGE - ComplyAdvantage (triagem de sançÔes e PEP)
  • WORLDCHECK - Refinitiv World-Check (triagem de conformidade)
Veja ReferĂȘncia de CĂłdigos de Provedores para lista completa.

​
Estrutura de Dados da Entidade Pessoa

O objeto entityData.person deve conter: 
{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number,
    "incomeCurrency": "string",
    "address": "string | object (veja nota sobre Formato de Endereço)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string",
    "email": "string",
    "phone": "string",
    "alternativePhone": "string",
    "idType": "national_id | passport | drivers_license | tax_id | other",
    "idNumber": "string",
    "isPep": boolean,
    "pepPosition": "string",
    "pepCountry": "string"
  }
}
Formato de Endereço: O campo address suporta ambos os formatos:
  • Formato string (simples): "Av. Paulista, 1000, SĂŁo Paulo, SP, Brazil"
  • Formato objeto (estruturado): 
    {
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "SĂŁo Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

​
Execução de Matriz de Risco

VocĂȘ pode executar automaticamente uma matriz de risco (regras de conformidade KYC) ao criar uma pessoa fornecendo o parĂąmetro riskMatrixId.

​
Como Funciona

  1. Obtenha seu ID de Matriz de Risco no painel do gu1 (formato: UUID)
  2. Inclua riskMatrixId na sua requisição de criação
  3. O sistema automaticamente:
    • Cria a entidade pessoa
    • Executa todas as regras KYC na matriz
    • Calcula a pontuação de risco
    • Gera alertas de conformidade se necessĂĄrio
    • Atualiza o status da pessoa com base nos resultados

​
Exemplo com Matriz de Risco

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

​
Combinado com Enriquecimentos

Para melhores resultados, combine a execução de matriz com enriquecimentos automåticos: 
{
  "type": "person",
  "name": "MarĂ­a GonzĂĄlez",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": ["NOSIS"],
    "checks": ["COMPLY_ADVANTAGE", "REPET"]
  },
  "entityData": {
    "person": {
      "firstName": "MarĂ­a",
      "lastName": "GonzĂĄlez",
      "dateOfBirth": "1985-03-15"
    }
  }
}
Fluxo de Execução:
  1. Entidade pessoa criada
  2. Enriquecimento NOSIS busca dados de identidade e crédito
  3. REPET verifica listas de vigilĂąncia
  4. ComplyAdvantage verifica sançÔes e status PEP
  5. Regras da matriz de risco avaliam todos os dados coletados
  6. Pontuação de risco final calculada
  7. Alertas de conformidade gerados se as regras forem acionadas

​
Resposta

​
success
boolean
Indica se a pessoa foi criada com sucesso
​
entity
object
O objeto pessoa criado incluindo:
  • id - ID interno do gu1
  • externalId - Seu ID externo
  • organizationId - ID da sua organização
  • type - Sempre “person”
  • name - Nome da pessoa
  • riskScore - Pontuação de risco inicial (0-100)
  • status - Status da pessoa
  • entityData - Dados especĂ­ficos da pessoa
  • attributes - Atributos personalizados
  • createdAt - Timestamp de criação
  • updatedAt - Timestamp da Ășltima atualização

​
Exemplo de Requisição

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "externalId": "customer_12345",
    "name": "MarĂ­a GonzĂĄlez",
    "countryCode": "AR",
    "taxId": "20-12345678-9",
    "entityData": {
      "person": {
        "firstName": "MarĂ­a",
        "lastName": "GonzĂĄlez",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    }
  }'

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

​
Respostas de Erro

​
400 Bad Request - Tax ID InvĂĄlido

{
  "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 - Campos ObrigatĂłrios Ausentes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for person creation",
    "details": {
      "missingFields": ["firstName", "lastName"],
      "requiredFields": ["firstName", "lastName", "dateOfBirth"],
      "countryCode": "AR"
    }
  },
  "entity": null
}

​
409 Conflict - Entidade Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "customer_12345",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

​
PrĂłximos Passos

ApĂłs criar uma pessoa, vocĂȘ pode:
  1. Obter Detalhes da Pessoa - Recuperar informaçÔes completas da pessoa
  2. Listar Pessoas - Consultar suas pessoas
  3. Atualizar Pessoa - Modificar dados da pessoa
  4. Criar Validação KYC - Iniciar processo de verificação KYC