> ## 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.
# Obtener enrichment normalizado
> Lee el dossier normalizado de Gu1 de una entidad — campos consolidados de enrichments ya ejecutados, sin volver a llamar a esas integraciones.
## Descripción general
Devuelve el **último dossier normalizado persistido** de una entidad: un JSON con forma Gu1 (`normalizedData`) fusionado a partir de todos los enrichments que ya corrieron sobre esa entidad.
Este endpoint es una **lectura**. **No** llama a integraciones externas y **no** consume créditos de enrichment. Para poblar o refrescar el dossier, usá [Ejecutar enrichment](/es/api-reference/enrichment/execute-by-id).
Usalo cuando necesitás el perfil **canónico** (flags PEP, sanciones, direcciones, procesos judiciales y los mismos paths que las reglas leen como `enrichmentData.normalized.*`). Para el último payload **mapped/raw por código de integración**, usá [Obtener datos actuales de enrichment](/es/api-reference/enrichment/get-current-data).
Requiere el permiso granular **`entities:read`** en la API key (fallback legacy `entities:read`).
## Endpoint
```
GET https://api.gu1.ai/entities/{id}/normalized-enrichment
```
## Autenticación
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Parámetros de ruta
UUID de la entidad en Gu1.
## Respuesta
Envelope: `{ "success": true, "data": { ... } }`.
UUID de la fila de enrichment normalizado.
UUID de la entidad.
UUID de la organización.
`person` o `company`.
Contrato flatten de normalización Gu1: **`RootData` ∩ arrays de consolidadores ∩ objetos `*Summary`** en el mismo JSON (no anidado como `{ root, consolidated }`). Mismas claves que las reglas leen en `enrichmentData.normalized.*`. Ver [contrato de normalizedData](#normalizeddata-contrato) abajo. Pueden aparecer claves legacy de mappers viejos; las integraciones nuevas deben usar solo este contrato.
Métricas de completitud y confianza recalculadas en lectura según el país de la entidad, más `recommendations` opcionales de enrichments adicionales.
Códigos de integración que aportaron a este dossier (por ejemplo `br_cpf_enrichment`). El nombre del campo JSON es `providersUsed`.
Score de calidad 0–100, cuando está presente.
Score de confianza 0–100, cuando está presente.
Score de completitud 0–100, cuando está presente.
Campos donde las fuentes discreparon y cómo los resolvió Gu1 (`field`, `values`, `resolution`, `selectedValue`, `confidence`).
Timestamp ISO 8601 de la fila.
Timestamp ISO 8601 de la última actualización.
## `normalizedData` contrato
TypeScript canónico: `NormalizeType = RootData & ToConsolidateType & SummariesType`.
Todas las claves son **opcionales**. La presencia depende del tipo de entidad (`person` / `company`), del país y de qué enrichments corrieron. Una clave ausente es “no poblada”, no `false` / `0`.
```ts theme={null}
type NormalizeType = RootData & ToConsolidateType & SummariesType;
```
Paths de reglas: `enrichmentData.normalized.` (for example `enrichmentData.normalized.isPep`, `enrichmentData.normalized.legalProceedings.$.type`). Catálogo completo de paths: [Condiciones de reglas](/es/api-reference/rules/conditions).
### Provenance en filas de consolidadores
Cada ítem de consolidadores suele incluir:
| Campo | Tipo | Significado |
| ---------------------------- | ---------- | ------------------------------------------------------------ |
| `sources` | `string[]` | Códigos de integración que reportaron esta fila |
| `providers` | `string[]` | Códigos de integración extra opcionales unidos al consolidar |
| `confirmedByMultipleSources` | `boolean` | `true` cuando coinciden 2+ fuentes |
| `confidence` | `number` | 0–100 |
| `count` | `number` | Cuántas fuentes lo reportaron (cuando está) |
### Root (`RootData`)
Escalares en `normalizedData` (flags de conveniencia + identidad). Para listas preferí consolidadores (`riskFlags`, `sanctions`, `addresses`).
**PEP**
| Clave | Tipo | Entidad | Notas |
| ------------------------ | ---------- | ------- | --------------------------------------------------------------------------------------- |
| `isPep` | `boolean` | both | Es o fue PEP alguna vez |
| `isCurrentPep` | `boolean` | both | PEP **actual** confirmado |
| `isPepPossible` | `boolean` | both | PEP posible (código PIA 2). No es un hit PEP completo; no lo trates como `isCurrentPep` |
| `pepLevels` | `string[]` | both | Niveles PEP históricos (p. ej. `"1"`, `"2"`) |
| `pepCountry` | `string` | both | País del status PEP |
| `pepPosition` | `string` | person | Último cargo conocido |
| `pepComplianceRowCount` | `number` | both | Filas PEP devueltas para el tax ID (PIA) |
| `lastYearPEPOccurence` | `number` | both | Ocurrencias del último año |
| `last3YearsPEPOccurence` | `number` | both | Últimos 3 años |
| `last5YearsPEPOccurence` | `number` | both | Últimos 5 años |
**Sanciones / media / terrorismo**
| Clave | Tipo | Entidad |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------- | ------- |
| `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 |
**Identidad y contacto**
| Clave | Tipo | Entidad |
| --------------------------------------------------------------------------- | -------------------------------------------- | ------- |
| `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 |
**Identidad de empresa**
| Clave | Tipo | Entidad |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `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 / empleo / AML (sobre todo AR)**
| Clave | Tipo | Entidad |
| ------------------------------------------------------------- | --------- | ------- |
| `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` es el listado texto/XML AFIP; la lista estructurada es `economicActivities`. `isAMLObligatedSubject` es sujeto obligado LA/FT (no PEP político). `isUifObligatedSubject` es inscripción UIF (distinto del SO Nosis).
**Crédito**
| Clave | Tipo | Entidad |
| ----------------------------------------------------------------- | ---------------- | ------- |
| `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` son códigos de situación 1–5 únicos.
**Electoral (métricas root)**
| Clave | Tipo | Entidad |
| ------------------------------ | --------- | ------- |
| `totalElectoralDonations` | `number` | both |
| `totalElectoralDonationAmount` | `number` | both |
| `isCurrentlyElectoralDonor` | `boolean` | both |
| `isHistoricalElectoralDonor` | `boolean` | both |
### Consolidadores (`ToConsolidateType` + summaries)
Los arrays viven junto a su `*Summary` en el mismo objeto. **P** = persona, **C** = empresa.
| Array | Summary | Alcance | Tipo de ítem |
| --------------------- | --------------------------------------------------------------- | ---------------------------- | ------------------------- |
| `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` | menciones 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` |
Las filas persistidas también pueden exponer `electoralActivity` (nombre legacy del array). Preferí `electoralActivities`.
#### Tipos de ítem
```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;
}
```
Los summaries (`addressesSummary`, `legalProceedingsSummary`, `shareholdersSummary`, …) exponen conteos, desgloses `byType` / `byStatus` y flags como `hasActiveCriminalCases`, `hasArrestWarrant`, `hasFamilyRelationships`. La forma coincide con las interfaces TypeScript `*Summary` de los tipos compartidos de consolidadores de Gu1.
## Errores
| HTTP | `error.code` | Cuándo |
| ----- | ---------------- | ------------------------------------------------------------------------ |
| `401` | `UNAUTHORIZED` | Falta el contexto de organización |
| `404` | `NOT_FOUND` | La entidad nunca tuvo enrichment, o el UUID no está en esta organización |
| `500` | `INTERNAL_ERROR` | Fallo inesperado |
Si todavía no hay fila normalizada, la API responde **404** (no un body vacío con `success: true`).
## Ejemplo
```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` en producción es mucho más grande que este ejemplo. Tomalo como pista de forma, no como schema completo.
## Relacionado
* [Obtener datos actuales de enrichment](/es/api-reference/enrichment/get-current-data) — último mapped/raw por código de integración
* [Ejecutar enrichment](/es/api-reference/enrichment/execute-by-id) — correr integraciones y persistir el dossier
* [Obtener entidad](/es/api-reference/entities/get) — identidad, estado y score de riesgo (no reemplaza este endpoint)
* [Condiciones de reglas](/es/api-reference/rules/conditions) — catálogo `enrichmentData.normalized.*`