Enrichment Overview

What is Enrichment?

Enrichment is the process of enhancing entity data by gathering additional information from external data providers. gu1 integrates with dozens of official government registries, credit bureaus, identity verification services, and other trusted data sources to provide comprehensive entity profiles.

How It Works

Select Entity: Choose the entity you want to enrich (by internal ID or your external ID)
Choose Providers: Select one or more enrichment integration codes
Execute: gu1 calls the external providers in parallel and normalizes the responses
Results: Get standardized enrichment data, quality metrics, and costs

Key Features

Batch Execution

Execute multiple enrichments in a single API call for better performance and convenience.

Cost Transparency

Each enrichment returns its individual cost in cents, and you get a total for the batch.

Quality Metrics

Every enrichment includes:

Completeness: How much of the requested data was found (0-1)
Confidence: Provider’s confidence in the data accuracy (0-1)

Automatic Audit Trail

All enrichments are automatically logged with:

Timestamp
Provider used
Fields enriched
Execution time
Cost

Rules Engine Integration

Successful enrichments automatically trigger the rules engine with the enrichment_completed event, allowing you to create automated workflows.

Marketplace fallbacks

Some catalog enrichments define a fallback chain: ordered substitute enrichments that Gu1 may try only after the primary fails.

They do not need to be enabled in Marketplace

For most catalog enrichments, fallback_requires_activation is false. Then a fallback does not have to be turned on in Marketplace to be eligible. Gu1 can run it when the primary fails even if that card is disabled for your organization. Keep it disabled if you only want it as a safety net. Enabling it in Marketplace (or listing it in autoExecuteIntegrations.enrichments / executeAllActiveEnrichments: true) makes it a regular enrichment: it runs on every matching automatic create and consumes credits even when the primary already succeeded. If the Marketplace card of the primary shows that fallbacks must be enabled first (fallback_requires_activation: true), then each substitute in the chain does need to be active for your organization before it can run.

When they run

Fallbacks run on automatic pipelines, for example:

Automatic entity creation — after basic-data retries, the org-effective chain of the primary is tried in order until one succeeds (or the chain is empty).
Additional enrichments on that same automatic create (after basic data) — if one listed enrichment fails, Gu1 may try that enrichment’s catalog chain.
Bulk entity import — same idea for automatic basic data (for example Argentina: Nosis when it is enabled; otherwise ARCA only if that card is also enabled).

They do not run on manual Marketplace execution: Execute by ID and Execute by External ID only run the codes you send. Those codes must be enabled for the organization. Automatic creation needs at least one code from that chain enabled in Marketplace: the primary, or a substitute. When the primary is active it runs first and substitutes are tried only if it fails. When the primary is off, the first enabled substitute is the source. If none is enabled, the response is HTTP 422 (error.code BASIC_DATA_ENRICHMENT_REQUIRED) and errors.creationFailed[].error carries the English sentence that lists the codes (Activate one of: …). That sentence is what the integrator receives; it is not replaced by a generic error. See Automatic entity creation.

How to configure the chain

Open the primary enrichment in Marketplace (/marketplace). The Fallback chain section lets you:

Keep Gu1 catalog defaults (typical: substitutes stay off as products and only run on failure).
Reorder, add, or remove catalog candidates (you cannot invent codes).
Save an empty chain so that if the primary fails, nothing else is tried.
Reset to the Gu1 default.

Credits are charged for each fallback attempt that actually executes, not for leaving the card disabled. If automatic creation identifies a minor and your organization has placeholder-name creation enabled, Gu1 skips retries, fallbacks, and extra enrichments on purpose. See failed automatic creates: enrichmentFailedDetails lists each attempt (primary + catalog fallbacks) when the entity was not created.

Available Endpoints

Execute by Internal ID

Execute enrichments using gu1’s internal entity UUID

Execute by External ID

Execute enrichments using your own entity identifier

Get normalized enrichment

Read the persisted Gu1 canonical dossier (normalizedData)

Get current enrichment data

Read last mapped and raw payloads by integration code

Common Integration Codes

Argentina

ar_repet_enrichment - Official person data from REPET
ar_renaper_enrichment - National identity registry
ar_bcra_enrichment - Central bank financial data
ar_bcra_deudas_enrichment - Central bank debt information
ar_afip_enrichment - Tax authority data
ar_nosis_enrichment - Credit bureau report

Brazil

br_serasa_enrichment - Serasa credit data
br_spc_enrichment - SPC credit bureau
br_receita_federal_enrichment - Federal revenue data
br_cpf_enrichment - CPF validation and data
br_cnpj_enrichment - CNPJ company data

Global

global_worldcheck_enrichment - Sanctions and PEP screening
global_dowjones_enrichment - Risk and compliance data

See Integration Provider Codes for the complete list.

Use Cases

KYC/KYB Onboarding

Gather official identity and company data during customer onboarding:

const result = await enrichEntity(customerId, [
  'ar_repet_enrichment',
  'ar_renaper_enrichment'
]);

Credit Assessment

Pull financial and credit data for risk evaluation:

const result = await enrichEntity(customerId, [
  'ar_bcra_enrichment',
  'ar_nosis_enrichment'
]);

Compliance Screening

Screen for sanctions, PEP status, and adverse media:

const result = await enrichEntity(entityId, [
  'global_worldcheck_enrichment',
  'global_dowjones_enrichment'
]);

Ongoing Monitoring

Periodically refresh entity data for continuous monitoring:

// Run monthly
const result = await enrichEntity(entityId, [
  'ar_bcra_deudas_enrichment',
  'ar_afip_enrichment'
]);

Best Practices

Execute related enrichments together for better performance:

// Good - batch related enrichments
await enrichEntity(id, [
  'ar_repet_enrichment',
  'ar_renaper_enrichment',
  'ar_bcra_enrichment'
]);

// Less optimal - separate calls
await enrichEntity(id, ['ar_repet_enrichment']);
await enrichEntity(id, ['ar_renaper_enrichment']);
await enrichEntity(id, ['ar_bcra_enrichment']);

2. Handle Partial Failures

Check individual results as some providers may fail while others succeed:

const result = await enrichEntity(id, providers);

result.results.forEach(r => {
  if (r.success) {
    // Process successful enrichment
    console.log(`✓ ${r.integrationName}`);
  } else {
    // Log failed enrichment
    console.warn(`✗ ${r.integrationName}: ${r.error.message}`);
  }
});

3. Track Costs

Monitor enrichment costs to optimize your integration usage:

const result = await enrichEntity(id, providers);

console.log(`Total cost: $${result.totalCostCents / 100}`);

// Track per-provider costs
result.results.forEach(r => {
  if (r.costCents > 0) {
    console.log(`${r.integrationName}: $${r.costCents / 100}`);
  }
});

4. Use External IDs for Convenience

If you work with your own identifiers, use the external ID endpoint:

// Simpler - use your ID
await enrichEntityByExternalId('customer_12345', providers);

// vs storing/looking up UUID
const uuid = await getEntityUUID('customer_12345');
await enrichEntity(uuid, providers);

5. Leverage Quality Metrics

Use completeness and confidence scores to assess data quality:

result.results.forEach(r => {
  if (r.success) {
    const quality = r.result.dataQuality;

    if (quality.completeness < 0.5) {
      console.warn('Low data completeness');
    }

    if (quality.confidence < 0.8) {
      console.warn('Low confidence - manual review recommended');
    }
  }
});

Error Handling

Enrichments can fail for various reasons:

Entity Not Found

{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found"
  }
}

Provider Errors

Individual provider failures don’t fail the entire batch:

{
  "success": true,
  "results": [
    {
      "success": false,
      "error": {
        "code": "NO_DATA_FOUND",
        "message": "No data found for this entity"
      }
    }
  ]
}

Rate Limiting

Some providers have rate limits - failures include retry information:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Provider rate limit exceeded",
    "retryAfter": 3600
  }
}

Next Steps

Explore Execute by ID for internal UUID-based enrichment
Learn about Execute by External ID for simplified integration
Read Marketplace fallbacks — substitutes on automatic pipelines, not on manual execute
Read the persisted normalized dossier or current mapped/raw data
Browse Provider Codes to see all available enrichments
Set up Rules to automate actions after enrichment

​What is Enrichment?

​How It Works

​Key Features

​Batch Execution

​Cost Transparency

​Quality Metrics

​Automatic Audit Trail

​Rules Engine Integration

​Marketplace fallbacks

​They do not need to be enabled in Marketplace

​When they run

​How to configure the chain

​Available Endpoints

Execute by Internal ID

Execute by External ID

Get normalized enrichment

Get current enrichment data

​Common Integration Codes

​Argentina

​Brazil

​Global

​Use Cases

​KYC/KYB Onboarding

​Credit Assessment

​Compliance Screening

​Ongoing Monitoring

​Best Practices

​1. Batch Related Enrichments

​2. Handle Partial Failures

​3. Track Costs

​4. Use External IDs for Convenience

​5. Leverage Quality Metrics

​Error Handling

​Entity Not Found

​Provider Errors

​Rate Limiting

​Next Steps