> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Criar uma entidade pessoa
> Criar uma nova pessoa com dados personalizados — para entidades de pessoa na plataforma KYC e análise de risco gu1, com exemplos para create.
## 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:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Corpo da Requisição
Deve ser `person` para criar uma entidade de pessoa
Seu identificador único para esta pessoa em seu sistema
Nome de exibição da pessoa
Código de país ISO 3166-1 alpha-2 (por exemplo, "US", "BR", "AR")
Número de identificação fiscal (validado com base no país)
📋 Ver [Formatos de Tax ID por País](/pt/api-reference/entities/tax-id-formats) para formatos aceitos e regras de validação para cada país.
Horário operacional opcional na **raiz** para regras KYT. Mesma forma que em [Criar entidade](/pt/api-reference/entities/create). Valores de `timezone`: [Enum fuso horário](/pt/api-reference/transactions/time-zone-enum).
**Opcional** - Atributos personalizados como pares chave-valor para metadados flexíveis
Use isto para campos personalizados que não se encaixam no esquema padrão (ex: IDs internos, tags, flags)
**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:**
```json theme={null}
{
"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):**
```json theme={null}
{
"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"
}
}
}
```
Data de registro da pessoa em formato ISO 8601 datetime (ex: "2024-01-15T10:30:00Z")
Marcar esta pessoa como cliente para fins de rastreamento
Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Se informados, após a criação o sistema avalia a pessoa **somente** contra regras ativas dessas matrizes (salvo `skipRulesExecution: true`). Mesma semântica que `riskMatrixIds` quando você envia um único id como string. Veja [Execução de Matriz de Risco](#execução-de-matriz-de-risco) abaixo.
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`.
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 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
* `expired` - Registro da pessoa expirou
* `deleted` - Excluído suavemente
* `rejected` - Pessoa foi rejeitada
Configurar a execução automática de enriquecimentos ao criar a pessoa.
**Estrutura:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
],
"excludeEnrichments": []
}
```
**Propriedades:**
* `executeAllActiveEnrichments` (boolean) - Executar todos os enriquecimentos ativos da org
* `enrichments` (string\[]) - Códigos a executar após criar a entidade
* `enrichmentGroupRefs` (string\[], opcional) - Slugs de grupos do Marketplace
* `excludeEnrichments` (string\[], opcional) - Códigos a omitir do conjunto final
Códigos `*_check` não fazem mais parte do contrato de criação; payloads legacy que os enviem são ignorados no parse.
Veja [Códigos de provedores](/pt/api-reference/integrations/person-provider-codes) e [Criar entidade](/pt/api-reference/entities/create).
Opcional. Só afeta enriquecimentos com **monitoramento contínuo** (hoje: **`global_gueno_sanctions_enrichment`**). Mesma semântica em [Criar entidade — monitoramento](/pt/api-reference/entities/create#exemplo-monitoramento-de-sancoes-gu1-ao-criar): `monitoring.main[código]` com `{ "watchlist": true }` (ou `true` legacy), o código em `enrichments` e monitoramento ON no Marketplace.
## Monitoramento de sanções Gu1 (pessoa)
```json theme={null}
{
"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": true
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": ["global_gueno_sanctions_enrichment"],
}
}
```
## Estrutura de Dados da Entidade Pessoa
O objeto `entityData.person` deve conter:
```json theme={null}
{
"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):
```json theme={null}
{
"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 ou mais matrizes de risco (regras de conformidade KYC) ao criar uma pessoa fornecendo `riskMatrixId` ou `riskMatrixIds`.
### Como Funciona
1. **Obtenha seu(s) ID(s) de Matriz de Risco** no painel do gu1 (formato: UUID)
2. **Inclua `riskMatrixId` ou `riskMatrixIds` 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
```json theme={null}
{
"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"
}
}
}
```
### Exemplo com várias matrizes de risco
```json theme={null}
{
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixIds": [
"550e8400-e29b-41d4-a716-446655440000",
"660e8400-e29b-41d4-a716-446655440001"
],
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
}
}
```
### Combinado com enriquecimentos e monitoramento Gu1
```json theme={null}
{
"type": "person",
"name": "María González",
"taxId": "20-12345678-9",
"countryCode": "AR",
"riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_renaper_data_enrichment",
"ar_repet_person_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
}
},
"entityData": {
"person": {
"firstName": "María",
"lastName": "González",
"dateOfBirth": "1985-03-15"
}
}
}
```
Ver [Criar entidade — monitoramento](/pt/api-reference/entities/create#exemplo-monitoramento-de-sancoes-gu1-ao-criar).
***
## Resposta
Indica se a pessoa foi criada com sucesso
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
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.
**Na raiz da resposta** (igual à API de transações). Mesmo valor que `rulesResult.rulesExecutionSummary`. **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**, **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 de Requisição
```bash cURL theme={null}
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"
}
}'
```
```javascript JavaScript theme={null}
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,
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'
}
})
});
const data = await response.json();
console.log(data.entity);
```
```python Python theme={null}
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,
'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'
}
}
)
entity = response.json()['entity']
print(entity)
```
## Exemplo de Resposta
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"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
```json theme={null}
{
"error": "Invalid or missing API key",
"code": "INVALID_KEY"
}
```
## Próximos Passos
Após criar uma pessoa, você pode:
1. [Obter Detalhes da Pessoa](/pt/api-reference/person/get) - Recuperar informações completas da pessoa
2. [Listar Pessoas](/pt/api-reference/person/list) - Consultar suas pessoas
3. [Atualizar Pessoa](/pt/api-reference/person/update) - Modificar dados da pessoa
4. [Criar Validação KYC](/pt/use-cases/kyc/create-validation) - Iniciar processo de verificação KYC