> ## 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.
# Obter enrichment normalizado
> Lê o dossiê normalizado da Gu1 de uma entidade — campos consolidados de enrichments já executados, sem chamar de novo essas integrações.
## Visão geral
Devolve o **último dossiê normalizado persistido** de uma entidade: um JSON no formato Gu1 (`normalizedData`) mesclado a partir de todos os enrichments que já rodaram nessa entidade.
Este endpoint é uma **leitura**. **Não** chama integrações externas e **não** consome créditos de enrichment. Para preencher ou atualizar o dossiê, use [Executar enrichment](/pt/api-reference/enrichment/execute-by-id).
Use quando precisar do perfil **canônico** (flags PEP, sanções, endereços, processos judiciais e os mesmos paths que as regras leem como `enrichmentData.normalized.*`). Para o último payload **mapped/raw por código de integração**, use [Obter dados atuais de enrichment](/pt/api-reference/enrichment/get-current-data).
Exige a permissão granular **`entities:read`** na API key (fallback legacy `entities:read`).
## Endpoint
```
GET https://api.gu1.ai/entities/{id}/normalized-enrichment
```
## Autenticação
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Parâmetros de rota
UUID da entidade na Gu1.
## Resposta
Envelope: `{ "success": true, "data": { ... } }`.
UUID da linha de enrichment normalizado.
UUID da entidade.
UUID da organização.
`person` ou `company`.
Contrato flatten de normalização Gu1: **`RootData` ∩ arrays de consolidadores ∩ objetos `*Summary`** no mesmo JSON (não aninhado como `{ root, consolidated }`). Mesmas chaves que as regras leem em `enrichmentData.normalized.*`. Consulte o [contrato de normalizedData](#normalizeddata-contrato) abaixo. Podem aparecer chaves legacy de mappers antigos; integrações novas devem usar só este contrato.
Métricas de completeza e confiança recalculadas na leitura conforme o país da entidade, mais `recommendations` opcionais de enrichments adicionais.
Códigos de integração que contribuíram para este dossiê (por exemplo `br_cpf_enrichment`). O nome do campo JSON é `providersUsed`.
Score de qualidade 0–100, quando presente.
Score de confiança 0–100, quando presente.
Score de completeza 0–100, quando presente.
Campos em que as fontes discordaram e como a Gu1 resolveu (`field`, `values`, `resolution`, `selectedValue`, `confidence`).
Timestamp ISO 8601 da linha.
Timestamp ISO 8601 da última atualização.
## `normalizedData` contrato
TypeScript canônico: `NormalizeType = RootData & ToConsolidateType & SummariesType`.
Todas as chaves são **opcionais**. A presença depende do tipo de entidade (`person` / `company`), do país e de quais enrichments rodaram. Uma chave ausente é “não preenchida”, não `false` / `0`.
```ts theme={null}
type NormalizeType = RootData & ToConsolidateType & SummariesType;
```
Paths de regras: `enrichmentData.normalized.` (for example `enrichmentData.normalized.isPep`, `enrichmentData.normalized.legalProceedings.$.type`). Catálogo completo de paths: [Condições de regras](/pt/api-reference/rules/conditions).
### Proveniência nas linhas dos consolidadores
Cada item de consolidadores costuma incluir:
| Campo | Tipo | Significado |
| ---------------------------- | ---------- | ------------------------------------------------------------- |
| `sources` | `string[]` | Códigos de integração que reportaram esta linha |
| `providers` | `string[]` | Códigos de integração extras opcionais unidos na consolidação |
| `confirmedByMultipleSources` | `boolean` | `true` quando 2+ fontes concordam |
| `confidence` | `number` | 0–100 |
| `count` | `number` | Quantas fontes reportaram (quando presente) |
### Root (`RootData`)
Escalares em `normalizedData` (flags de conveniência + identidade). Para listas, prefira consolidadores (`riskFlags`, `sanctions`, `addresses`).
**PEP**
| Chave | Tipo | Entidade | Notas |
| ------------------------ | ---------- | -------- | ------------------------------------------------------------------------------------- |
| `isPep` | `boolean` | both | É ou foi PEP alguma vez |
| `isCurrentPep` | `boolean` | both | PEP **atual** confirmado |
| `isPepPossible` | `boolean` | both | PEP possível (código PIA 2). Não é um hit PEP completo; não trate como `isCurrentPep` |
| `pepLevels` | `string[]` | both | Níveis PEP históricos (ex. `"1"`, `"2"`) |
| `pepCountry` | `string` | both | País do status PEP |
| `pepPosition` | `string` | person | Último cargo conhecido |
| `pepComplianceRowCount` | `number` | both | Linhas PEP devolvidas para o tax ID (PIA) |
| `lastYearPEPOccurence` | `number` | both | Ocorrências no último ano |
| `last3YearsPEPOccurence` | `number` | both | Últimos 3 anos |
| `last5YearsPEPOccurence` | `number` | both | Últimos 5 anos |
**Sanções / mídia / terrorismo**
| Chave | Tipo | Entidade |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------- | -------- |
| `sanctioned` | `boolean` | both |
| `wasPreviouslySanctioned` | `boolean` | both |
| `last30DaysSanctions` / `last90DaysSanctions` / `last180DaysSanctions` / `last365DaysSanctions` | `number` | both |
| `terrorismRegistryMatch` | `boolean` | both |
| `terrorismRegistryActive` | `boolean` | both |
| `terrorismRiskLevel` | `'LOW' \| 'MEDIUM' \| 'HIGH' \| 'CRITICAL'` | both |
| `hasAdverseMedia` | `boolean` | both |
| `adverseMediaScore` | `number` | both |
| `criminalRecords` | `boolean` | both |
| `esgScore` | `number` | both |
| `esgPositiveNewsCount` / `esgNegativeNewsCount` | `number` | both |
**Identidade e contato**
| Chave | Tipo | Entidade |
| --------------------------------------------------------------------------- | -------------------------------------------- | -------- |
| `taxId` | `string` | both |
| `fullName` / `firstName` / `lastName` | `string` | person |
| `idNumber` / `idType` | `string` | person |
| `dateOfBirth` | `string` | person |
| `age` | `number` | person |
| `gender` | `'male' \| 'female' \| 'unknown' \| 'other'` | person |
| `nationality` | `string` | person |
| `isDeceased` | `boolean` | both |
| `deathYear` | `number` | person |
| `motherName` / `fatherName` | `string` | person |
| `socialSecurityNumber` | `string \| null` | person |
| `email` / `phone` / `address` / `city` / `state` / `country` / `postalCode` | `string` | both |
| `occupation` / `employer` | `string` | person |
| `incomeRange` / `totalAssetsCategory` | `string` | person |
**Identidade da empresa**
| Chave | Tipo | Entidade |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- |
| `legalName` / `tradeName` | `string` | company |
| `registrationNumber` / `registrationCountry` | `string` | company |
| `incorporationDate` / `inicioAtividade` | `string` | company |
| `situationDate` | `string` | company |
| `situation` | `'ATIVA' \| 'SUSPENSA' \| 'INAPTA' \| 'BAIXADA' \| 'NULA' \| 'REGULAR' \| 'IRREGULAR' \| 'TITULAR FALECIDO' \| 'UNKNOWN' \| 'PENDING' \| 'PENDING_REGULARIZATION'` | company |
| `tipo` / `legalForm` / `size` | `string` | company |
| `status` | `number` | company |
| `isMEI` / `isSimples` | `boolean` | company |
| `companyAge` | `number` | company |
| `registrationUptimeMonths` | `number` | company |
| `revenue` | `number` | company |
| `employeeCount` | `number` | company |
**Fiscal / emprego / AML (principalmente AR)**
| Chave | Tipo | Entidade |
| ------------------------------------------------------------- | --------- | -------- |
| `isMonotributo` / `isIvaRegistered` / `isIncomeTaxRegistered` | `boolean` | both |
| `isAutonomous` | `boolean` | person |
| `afipSeniority` | `number` | both |
| `afipRegistrationDate` | `string` | both |
| `monotributoCategory` / `monotributoActivityDescription` | `string` | both |
| `ivaCondition` / `incomeTaxCondition` | `string` | both |
| `mainActivityAfipCode` / `mainActivityAfipDescription` | `string` | both |
| `activities` | `string` | both |
| `uifInscription` | `string` | both |
| `isMyPyme` | `boolean` | both |
| `isAMLObligatedSubject` | `boolean` | both |
| `isUifObligatedSubject` | `boolean` | both |
| `laftHomonymsCount` | `number` | person |
| `isEmployee` / `isRetired` | `boolean` | person |
| `isEmployer` | `boolean` | both |
| `employmentSeniority` | `number` | person |
| `wasEmployedLast12Months` | `boolean` | person |
| `isMemberOfCompany` | `boolean` | person |
`activities` é a lista texto/XML AFIP; a lista estruturada é `economicActivities`. `isAMLObligatedSubject` é sujeito obrigado LA/FT (não PEP político). `isUifObligatedSubject` é inscrição UIF (distinto do SO Nosis).
**Crédito**
| Chave | Tipo | Entidade |
| ----------------------------------------------------------------- | ---------------- | -------- |
| `totalDebt` | `number \| null` | both |
| `debtorStatus` | `string \| null` | both |
| `worstCreditSituation` | `number \| null` | both |
| `totalCurrentDebt` / `averageMonthlyDebt` / `totalHistoricalDebt` | `number` | both |
| `worstHistoricalSituation` | `string` | both |
| `totalFinancialEntities` / `periodsAnalyzed` | `number` | both |
| `hasActiveRevisions` / `hasActiveLegalProcesses` | `boolean` | both |
| `reasonsBouncedChecks` | `string[]` | both |
| `debtSituation` | `number[]` | both |
`debtSituation` são códigos de situação 1–5 únicos.
**Eleitoral (métricas root)**
| Chave | Tipo | Entidade |
| ------------------------------ | --------- | -------- |
| `totalElectoralDonations` | `number` | both |
| `totalElectoralDonationAmount` | `number` | both |
| `isCurrentlyElectoralDonor` | `boolean` | both |
| `isHistoricalElectoralDonor` | `boolean` | both |
### Consolidadores (`ToConsolidateType` + summaries)
Os arrays ficam ao lado do `*Summary` no mesmo objeto. **P** = pessoa, **C** = empresa.
| Array | Summary | Escopo | Tipo do item |
| --------------------- | --------------------------------------------------------------- | -------------------------- | ------------------------- |
| `addresses` | `addressesSummary` | P+C | `AddressRecord` |
| `aliases` | `aliasesSummary` | P+C | `AliasRecord` |
| `documents` | `documentsSummary` | P+C | `DocumentRecord` |
| `emails` | `emailsSummary` | P+C | `EmailRecord` |
| `phones` | `phonesSummary` | P+C | `PhoneRecord` |
| `relationships` | `relationshipsSummary` | P+C | `RelationshipRecord` |
| `riskFlags` | `riskFlagsSummary` | P+C | `RiskFlagRecord` |
| `sanctions` | `sanctionsSummary` | P+C | `SanctionEntry` |
| `legalProceedings` | `legalProceedingsSummary` | P+C | `LegalProceeding` |
| `violations` | `violationsSummary` | P+C | `ViolationRecord` |
| `mediaMentions` | `mediaSummary` | menções P+C; **summary C** | `MediaMention` |
| `economicActivities` | `economicActivitiesSummary` | P+C | `EconomicActivityRecord` |
| `cnaes` | `cnaesSummary` | C | `CNAERecord` |
| `shareholders` | `shareholdersSummary` | C | `ShareholderRecord` |
| `demographics` | `demographicsSummary` | P | `DemographicRecord` |
| `occupations` | `occupationsSummary` | P | `OccupationRecord` |
| `taxReturns` | `taxReturnsSummary` | P | `TaxReturnRecord` |
| `electoralActivities` | `electoralActivitySummary` (alias `electoralActivitiesSummary`) | P | `ElectoralDonationRecord` |
As linhas persistidas também podem expor `electoralActivity` (nome legado do array). Prefira `electoralActivities`.
#### Tipos de item
```ts theme={null}
interface AddressRecord {
streetName: string;
city: string;
state: string;
country: string;
fullAddress: string;
streetType?: string;
number?: string;
complement?: string;
neighborhood?: string;
postalCode?: string;
type?: 'residential' | 'commercial' | 'correspondence' | 'unknown';
priority?: number;
isMainForEntity?: boolean;
isActive?: boolean;
isCurrent?: boolean;
latitude?: number;
longitude?: number;
geoQuality?: 'ROOFTOP' | 'RANGE_INTERPOLATED' | 'APPROXIMATE' | 'UNKNOWN';
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
firstSeenDate?: string;
lastSeenDate?: string;
}
interface DocumentRecord {
value: string;
formatted: string;
type: 'cnpj' | 'cpf' | 'rg' | 'passport' | 'other';
classification: 'main' | 'branch' | 'secondary' | 'unknown';
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
active?: boolean;
isPrimary?: boolean;
}
interface EmailRecord {
address: string;
normalizedAddress: string;
type?: 'work' | 'personal' | 'business' | 'unknown';
domain?: string;
isMainForEntity?: boolean;
isActive?: boolean;
isValidated?: boolean;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
}
interface PhoneRecord {
number: string;
normalizedNumber: string;
countryCode: string;
areaCode?: string;
localNumber?: string;
type?: 'mobile' | 'landline' | 'voip' | 'unknown';
category?: 'work' | 'personal' | 'unknown';
isMainForEntity?: boolean;
isActive?: boolean;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
}
interface AliasRecord {
name: string;
originalName: string;
type: 'former_name' | 'trade_name' | 'abbreviation' | 'facility_name' | 'subsidiary' | 'variation' | 'unknown';
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
}
interface DemographicRecord {
dateOfBirth?: string;
age?: number;
gender?: 'M' | 'F' | 'O' | 'UNKNOWN';
nationality?: string;
maritalStatus?: string;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
}
interface OccupationRecord {
occupation?: string;
employer?: string;
employerTaxId?: string;
income?: number;
incomeRange?: string;
currency?: string;
isCurrent?: boolean;
isPrimary?: boolean;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
}
interface RelationshipRecord {
relatedEntityName: string;
relatedEntityTaxId?: string;
relatedEntityType?: 'person' | 'company';
relationshipType:
| 'MOTHER' | 'FATHER' | 'PARENT' | 'BROTHER' | 'SISTER' | 'SIBLING'
| 'SON' | 'DAUGHTER' | 'COUSIN' | 'UNCLE' | 'NEPHEW' | 'NIECE' | 'RELATIVE'
| 'SPOUSE' | 'PARTNER' | 'BUSINESS_PARTNER' | 'COWORKER' | 'NEIGHBOR' | 'HOUSEHOLD' | 'OTHER';
relationshipLevel?: 'DIRECT' | 'INDIRECT';
isActive?: boolean;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
}
interface RiskFlagRecord {
flagType: 'PEP' | 'SANCTION' | 'ADVERSE_MEDIA' | 'CRIMINAL_RECORD' | 'OTHER';
isActive: boolean;
details?: {
pepPosition?: string;
pepCountry?: string;
pepLevel?: 'national' | 'international' | 'local';
sanctionLists?: string[];
mediaScore?: number;
severity?: 'low' | 'medium' | 'high' | 'critical';
description?: string;
riskScore?: number;
};
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
}
interface SanctionEntry {
id: string;
listName: string;
sanctionedName: string;
status?: 'active' | 'removed' | 'expired';
type?: string;
reason?: string;
addedDate?: string;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
confidence: number;
}
interface LegalProceeding {
id: string;
type: 'arrest_warrant' | 'criminal' | 'civil' | 'labor' | 'public_ministry'
| 'special_civil' | 'special_criminal' | 'administrative' | 'electoral'
| 'fazenda' | 'special_fazenda' | 'tributario' | 'previdenciaria' | 'unknown';
subject: string;
category:
| 'fraude' | 'corrupcao' | 'lavagem_dinheiro' | 'crimes_ambientais'
| 'trabalho_escravo' | 'sonegacao_fiscal' | 'crimes_financeiros'
| 'crimes_patrimoniais' | 'civil_dispute' | 'labor_dispute'
| 'investigation' | 'warrant' | 'other';
status?: 'active' | 'closed' | 'pending' | 'unknown';
processoNumber?: string;
court?: string;
parties?: Array<{ name: string; role: string }>;
sources: string[];
confirmedByMultipleSources: boolean;
severity: 'low' | 'medium' | 'high' | 'critical';
confidence: number;
amount?: number;
currency?: string;
}
interface ViolationRecord {
id: string;
displayName: string;
category: 'environmental' | 'labor' | 'financial' | 'governance'
| 'administrative' | 'consumer' | 'tax' | 'public_order' | 'other';
severity: 'low' | 'medium' | 'high' | 'critical';
sources: string[];
confirmedByMultipleSources: boolean;
count: number;
}
interface MediaMention {
id: string;
title: string;
description: string;
sentiment: 'positive' | 'negative' | 'neutral';
category: 'award' | 'recognition' | 'partnership' | 'investment'
| 'condemnation' | 'investigation' | 'lawsuit' | 'fine' | 'violation' | 'other';
date?: string;
amount?: number;
currency?: string;
sources: string[];
confirmedByMultipleSources: boolean;
confidence: number;
severity?: 'low' | 'medium' | 'high' | 'critical';
}
interface EconomicActivityRecord {
description: string;
code?: string;
isMain?: boolean;
activityRank?: 'main' | 'secondary' | 'tertiary';
startDate?: string;
countryCode?: string;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
confidence: number;
}
interface CNAERecord {
code: string;
description: string;
isMain: boolean;
isHighRisk?: boolean;
secao?: string;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
confidence: number;
}
interface ShareholderRecord {
name: string;
taxId?: string;
taxIdType?: string;
entityType?: 'person' | 'company' | 'unknown';
relationshipType: 'SOCIO_ADMINISTRADOR' | 'ADMINISTRADOR' | 'SOCIO' | 'QSA'
| 'PROCURADOR' | 'REPRESENTANTE' | 'TITULAR' | 'UNKNOWN';
ownershipPercentage?: number;
isActive: boolean;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
legalProceedings?: LegalProceeding[];
}
interface TaxReturnRecord {
year: string;
status: string;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
}
interface ElectoralDonationRecord {
year: string;
amountDonated: number;
donationsCount: number;
sources: string[];
providers?: string[];
confirmedByMultipleSources: boolean;
count: number;
confidence: number;
currency?: string;
}
```
Os summaries (`addressesSummary`, `legalProceedingsSummary`, `shareholdersSummary`, …) expõem contagens, breakdowns `byType` / `byStatus` e flags como `hasActiveCriminalCases`, `hasArrestWarrant`, `hasFamilyRelationships`. A forma coincide com as interfaces TypeScript `*Summary` dos tipos compartilhados de consolidadores da Gu1.
## Erros
| HTTP | `error.code` | Quando |
| ----- | ---------------- | ---------------------------------------------------------------------- |
| `401` | `UNAUTHORIZED` | Falta o contexto da organização |
| `404` | `NOT_FOUND` | A entidade nunca teve enrichment, ou o UUID não está nesta organização |
| `500` | `INTERNAL_ERROR` | Falha inesperada |
Se ainda não existir linha normalizada, a API responde **404** (não um body vazio com `success: true`).
## Exemplo
```bash cURL theme={null}
curl -X GET "https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/normalized-enrichment" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```javascript JavaScript theme={null}
const response = await fetch(
'https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/normalized-enrichment',
{ headers: { Authorization: 'Bearer YOUR_API_KEY' } }
);
const body = await response.json();
```
```python Python theme={null}
import requests
response = requests.get(
'https://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000/normalized-enrichment',
headers={'Authorization': 'Bearer YOUR_API_KEY'}
)
print(response.json())
```
```json theme={null}
{
"success": true,
"data": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"entityId": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "11111111-2222-3333-4444-555555555555",
"entityType": "person",
"normalizedData": {
"taxId": "12345678901",
"fullName": "Example Person",
"isPep": false,
"isCurrentPep": false,
"isPepPossible": false,
"sanctioned": false,
"country": "BR",
"addresses": [
{
"streetName": "Example Street",
"city": "Sao Paulo",
"state": "SP",
"country": "BR",
"fullAddress": "Example Street, 100, Sao Paulo, SP, BR",
"sources": ["br_cpf_enrichment"],
"confirmedByMultipleSources": false,
"count": 1
}
]
},
"normalizedMetrics": {
"completeness": 0.72,
"confidence": 0.9
},
"providersUsed": ["br_cpf_enrichment"],
"dataQualityScore": 80,
"confidenceScore": 90,
"completenessScore": 72,
"conflicts": [],
"createdAt": "2026-09-01T12:00:00.000Z",
"updatedAt": "2026-09-03T15:30:00.000Z"
}
}
```
`normalizedData` em produção é bem maior que este exemplo. Trate-o como pista de forma, não como schema completo.
## Relacionado
* [Obter dados atuais de enrichment](/pt/api-reference/enrichment/get-current-data) — último mapped/raw por código de integração
* [Executar enrichment](/pt/api-reference/enrichment/execute-by-id) — rodar integrações e persistir o dossiê
* [Obter entidade](/pt/api-reference/entities/get) — identidade, status e score de risco (não substitui este endpoint)
* [Condições de regras](/pt/api-reference/rules/conditions) — catálogo `enrichmentData.normalized.*`