> ## 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.
# Get normalized enrichment
> Read the Gu1-normalized dossier for an entity — consolidated fields from enrichments already run, without calling those integrations again.
## Overview
Returns the **latest persisted normalized dossier** for an entity: one Gu1-shaped JSON (`normalizedData`) merged from every enrichment that has already run on that entity.
This endpoint is a **read**. It does **not** call external integrations and does **not** consume enrichment credits. To populate or refresh the dossier, use [Execute enrichment](/en/api-reference/enrichment/execute-by-id).
Use this when you need the **canonical** profile (PEP flags, sanctions, addresses, legal proceedings, and the same paths rules use as `enrichmentData.normalized.*`). For the last **mapped/raw payload keyed by integration code**, use [Get current enrichment data](/en/api-reference/enrichment/get-current-data).
Requires granular permission **`entities:read`** on the API key (legacy fallback `entities:read`).
## Endpoint
```
GET https://api.gu1.ai/entities/{id}/normalized-enrichment
```
## Authentication
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Path parameters
Gu1 entity UUID.
## Response
Envelope: `{ "success": true, "data": { ... } }`.
UUID of the normalized enrichment row.
Entity UUID.
Organization UUID.
`person` or `company`.
Flattened Gu1 normalize contract: **`RootData` ∩ consolidator arrays ∩ `*Summary` objects** on the same JSON object (not nested as `{ root, consolidated }`). Same keys rules read as `enrichmentData.normalized.*`. See [normalizedData contract](#normalizeddata-contract) below. Extra legacy keys from older mappers may appear; new integrations should use this contract only.
Completeness and confidence metrics recalculated on read for the entity country, plus optional `recommendations` for further enrichments.
Integration codes that contributed to this dossier (for example `br_cpf_enrichment`). JSON field name is `providersUsed`.
Overall quality score 0–100, when present.
Confidence score 0–100, when present.
Completeness score 0–100, when present.
Fields where sources disagreed and how Gu1 resolved them (`field`, `values`, `resolution`, `selectedValue`, `confidence`).
ISO 8601 timestamp of the row.
ISO 8601 timestamp of the last update.
## `normalizedData` contract
Canonical TypeScript: `NormalizeType = RootData & ToConsolidateType & SummariesType`.
All keys are **optional**. Presence depends on entity type (`person` / `company`), country, and which enrichments ran. A missing key is “not populated”, not `false` / `0`.
```ts theme={null}
type NormalizeType = RootData & ToConsolidateType & SummariesType;
```
Rules paths: `enrichmentData.normalized.` (for example `enrichmentData.normalized.isPep`, `enrichmentData.normalized.legalProceedings.$.type`). Full path catalog: [Rule conditions](/en/api-reference/rules/conditions).
### Provenance on consolidator rows
Every consolidator item typically includes:
| Field | Type | Meaning |
| ---------------------------- | ---------- | ------------------------------------------------------ |
| `sources` | `string[]` | Integration codes that reported this row |
| `providers` | `string[]` | Optional extra integration codes merged on consolidate |
| `confirmedByMultipleSources` | `boolean` | `true` when 2+ sources agree |
| `confidence` | `number` | 0–100 |
| `count` | `number` | How many sources reported it (when present) |
### Root (`RootData`)
Scalars on `normalizedData` (convenience flags + identity). Prefer consolidators for lists (`riskFlags`, `sanctions`, `addresses`).
**PEP**
| Key | Type | Entity | Notes |
| ------------------------ | ---------- | ------ | ----------------------------------------------------------------------------- |
| `isPep` | `boolean` | both | Is or was PEP at any time |
| `isCurrentPep` | `boolean` | both | Confirmed **current** PEP |
| `isPepPossible` | `boolean` | both | Possible PEP (PIA code 2). Not a full PEP hit; do not treat as `isCurrentPep` |
| `pepLevels` | `string[]` | both | Historical PEP levels (e.g. `"1"`, `"2"`) |
| `pepCountry` | `string` | both | Country of PEP status |
| `pepPosition` | `string` | person | Last known position |
| `pepComplianceRowCount` | `number` | both | PEP rows returned for the tax ID (PIA) |
| `lastYearPEPOccurence` | `number` | both | Occurrences last year |
| `last3YearsPEPOccurence` | `number` | both | Last 3 years |
| `last5YearsPEPOccurence` | `number` | both | Last 5 years |
**Sanctions / media / terrorism**
| Key | Type | Entity |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------- | ------ |
| `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 |
**Identity & contact**
| Key | Type | Entity |
| --------------------------------------------------------------------------- | -------------------------------------------- | ------ |
| `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 |
**Company identity**
| Key | Type | Entity |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `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 / employment / AML (mostly AR)**
| Key | Type | Entity |
| ------------------------------------------------------------- | --------- | ------ |
| `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` is the AFIP text/XML list; the structured list is `economicActivities`. `isAMLObligatedSubject` is LA/FT obligated subject (not political PEP). `isUifObligatedSubject` is UIF inscription (distinct from Nosis SO).
**Credit**
| Key | Type | Entity |
| ----------------------------------------------------------------- | ---------------- | ------ |
| `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` are unique situation codes 1–5.
**Electoral (root metrics)**
| Key | Type | Entity |
| ------------------------------ | --------- | ------ |
| `totalElectoralDonations` | `number` | both |
| `totalElectoralDonationAmount` | `number` | both |
| `isCurrentlyElectoralDonor` | `boolean` | both |
| `isHistoricalElectoralDonor` | `boolean` | both |
### Consolidators (`ToConsolidateType` + summaries)
Arrays live next to their `*Summary` on the same object. **P** = person, **C** = company.
| Array | Summary | Scope | Item type |
| --------------------- | --------------------------------------------------------------- | --------------------------- | ------------------------- |
| `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` | mentions 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` |
Persisted rows may also expose `electoralActivity` (legacy array name). Prefer `electoralActivities`.
#### Item types
```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;
}
```
Summaries (`addressesSummary`, `legalProceedingsSummary`, `shareholdersSummary`, …) expose counts, `byType` / `byStatus` breakdowns, and flags such as `hasActiveCriminalCases`, `hasArrestWarrant`, `hasFamilyRelationships`. Shape matches the TypeScript `*Summary` interfaces in the Gu1 shared consolidator types.
## Errors
| HTTP | `error.code` | When |
| ----- | ---------------- | ------------------------------------------------------------------------------ |
| `401` | `UNAUTHORIZED` | Missing organization context |
| `404` | `NOT_FOUND` | Entity has never been enriched, or the entity UUID is not in this organization |
| `500` | `INTERNAL_ERROR` | Unexpected failure |
If no normalized row exists yet, the API returns **404** (it does not return an empty `success: true` body).
## Example
```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
}
],
"addressesSummary": {
"totalAddresses": 1,
"uniqueAddresses": 1,
"confirmedAddresses": 0,
"activeAddresses": 1,
"hasMultipleAddresses": false
}
},
"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` in production is much larger. Use the [contract](#normalizeddata-contract) as the schema; this sample is only a shape hint.
## Related
* [Get current enrichment data](/en/api-reference/enrichment/get-current-data) — last mapped/raw by integration code
* [Execute enrichment](/en/api-reference/enrichment/execute-by-id) — run integrations and persist the dossier
* [Get entity](/en/api-reference/entities/get) — identity, status, and risk score (does not replace this endpoint)
* [Rule conditions](/en/api-reference/rules/conditions) — `enrichmentData.normalized.*` field catalog