Execute Enrichment

curl --request POST \
  --url http://api.gu1.ai/integration-execution/marketplace/enrichment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "integrationCodes": [
    "<string>"
  ],
  "parameters": {}
}
'

{
  "success": true,
  "results": [
    {}
  ],
  "totalCostCents": 123,
  "totalExecutionTime": 123,
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

integration-execution

marketplace

enrichment

Execute Enrichment

curl --request POST \
  --url http://api.gu1.ai/integration-execution/marketplace/enrichment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": "<string>",
  "integrationCodes": [
    "<string>"
  ],
  "parameters": {}
}
'

{
  "success": true,
  "results": [
    {}
  ],
  "totalCostCents": 123,
  "totalExecutionTime": 123,
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

Overview

Execute one or more marketplace enrichment integrations to enhance entity data with information from external providers. Enrichments add additional fields to the entity without performing risk assessment. This endpoint supports batch execution of multiple enrichments in a single request, optimizing cost and performance.

Endpoint

POST http://api.gu1.ai/integration-execution/marketplace/enrichment

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

entityId

string

required

UUID of the entity (company or person) to enrich

integrationCodes

array<string>

required

Array of enrichment integration codes to execute. See Provider Codes Reference for available codes.At least one integration code is required.

parameters

object

Optional additional parameters for the integrations (default: {})

Response

success

boolean

Whether all enrichments succeeded

results

array<object>

Array of individual enrichment results. Each result contains:

success (boolean) - Whether this enrichment succeeded
enrichmentId (string) - ID for viewing enrichment details
integrationCode (string) - The integration code that was executed
result (object) - Enrichment result data:
- fieldsEnriched (array<string>) - List of fields that were enriched
- dataQuality (object) - Data quality metrics
- summary (string) - Human-readable summary
- enrichmentData (object) - The enriched data
executionTime (number) - Execution time in milliseconds
costCents (number) - Cost in cents
error (object, optional) - Error details if failed

totalCostCents

number

Total cost for all enrichments in cents

totalExecutionTime

number

Total execution time for all enrichments in milliseconds

rulesResult

object

Result of rules execution when the rules engine runs after enrichment (if configured). When present, includes:

success (boolean) - Whether rules executed successfully
rulesTriggered (number) - Number of rules that were triggered
alerts (array) - Alerts generated by rules
riskScore (number) - Final calculated risk score
decision (string) - Final decision (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)
rulesExecutionSummary (object) - When rules ran, detailed summary; see below.

rulesExecutionSummary

object

At the root of the response (same as transactions API). Same value as rulesResult.rulesExecutionSummary. Only present when rules ran after enrichment. Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score.

rulesHit (array) - Rules whose conditions were met. Each item: name, description, score, priority, category, status, conditions, actions.
rulesNoHit (array) - Rules evaluated but conditions not met. Same structure as rulesHit.
actionsExecuted (object) - Aggregated executed actions: alerts, suggestion, status, assignedUser, customKeys (array of strings, optional) — custom action keys from rules that matched; for integrations/workflows.
totalScore (number) - Sum of score of all rules that hit (excluding shadow).

Examples

Execute Single Enrichment

curl -X POST http://api.gu1.ai/integration-execution/marketplace/enrichment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationCodes": ["br_cpfcnpj_complete_person_enrichment"]
  }'

Execute Multiple Enrichments (Batch)

curl -X POST http://api.gu1.ai/integration-execution/marketplace/enrichment \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "integrationCodes": [
      "br_cpfcnpj_complete_person_enrichment",
      "br_serpro_cpf_status_enrichment",
      "global_clear_sale_person_enrichment"
    ]
  }'

Response Example

Successful Enrichment

{
  "success": true,
  "results": [
    {
      "success": true,
      "enrichmentId": "enrich_abc123",
      "integrationCode": "br_cpfcnpj_complete_person_enrichment",
      "result": {
        "fieldsEnriched": [
          "fullName",
          "dateOfBirth",
          "taxId",
          "address",
          "city",
          "state",
          "postalCode"
        ],
        "dataQuality": {
          "overall": 85,
          "completeness": 90,
          "confidence": 85,
          "freshness": 100,
          "consistency": 100,
          "sourceReliability": "high",
          "lastUpdated": "2024-12-24T10:30:00.000Z"
        },
        "summary": "Enriched 7 fields from CPF/CNPJ Complete Enrichment",
        "enrichmentData": {
          "fullName": "João Silva",
          "dateOfBirth": "1985-05-15",
          "taxId": "123.456.789-00",
          "address": {
            "street": "Rua Example",
            "number": "123",
            "city": "São Paulo",
            "state": "SP",
            "postalCode": "01234-567"
          }
        }
      },
      "executionTime": 342,
      "costCents": 100
    }
  ],
  "totalCostCents": 100,
  "totalExecutionTime": 342,
  "rulesResult": null
}

Partial Failure (Some Enrichments Failed)

{
  "success": false,
  "results": [
    {
      "success": true,
      "enrichmentId": "enrich_abc123",
      "integrationCode": "br_cpfcnpj_complete_person_enrichment",
      "result": { ... },
      "executionTime": 342,
      "costCents": 100
    },
    {
      "success": false,
      "integrationCode": "br_serpro_cpf_status_enrichment",
      "executionTime": 150,
      "costCents": 0,
      "error": {
        "code": "PROVIDER_ERROR",
        "message": "CPF not found in Serpro database"
      }
    }
  ],
  "totalCostCents": 100,
  "totalExecutionTime": 492
}

Error Responses

404 Not Found - Entity Not Found

{
  "success": false,
  "results": [],
  "totalCostCents": 0,
  "totalExecutionTime": 0,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "Entity not found"
  }
}

400 Bad Request - Invalid Integration Code

{
  "success": false,
  "results": [],
  "totalCostCents": 0,
  "totalExecutionTime": 0,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one integration code is required"
  }
}

401 Unauthorized

{
  "success": false,
  "results": [],
  "totalCostCents": 0,
  "totalExecutionTime": 0,
  "error": {
    "code": "MISSING_ORGANIZATION",
    "message": "Organization ID is required"
  }
}

Pricing

Each enrichment has its own cost (see integration catalog)
Failed enrichments are NOT charged
Costs are deducted from your organization’s token balance
1 token = 100 cents = $1.00 USD

Best Practices

Batch Enrichments: Execute multiple enrichments in one request to optimize performance
Error Handling: Check individual success fields in results array
Cost Management: Monitor totalCostCents to track usage
Provider Selection: Choose enrichments based on your entity’s country and required fields
View Details: Use the enrichmentId to view complete enrichment details later

Automatic Rules Execution

When enrichments succeed, the rules engine may automatically execute based on your risk matrix configuration. The rulesResult field contains the rules execution outcome.

Use Cases

Progressive Data Enrichment

// Start with basic enrichment
const basicResponse = await enrichEntity(entityId, [
  'br_cpfcnpj_basic_person_enrichment'
]);

// If more data needed, run complete enrichment
if (basicResponse.results[0].result.dataQuality.overall < 80) {
  await enrichEntity(entityId, [
    'br_cpfcnpj_complete_person_enrichment'
  ]);
}

Multi-Provider Strategy

# Enrich from multiple providers for redundancy
integrations = [
    'br_cpfcnpj_complete_person_enrichment',
    'br_serpro_cpf_validation_enrichment',
    'global_clear_sale_person_enrichment'
]

response = enrich_entity(entity_id, integrations)

# Use data from the provider with best quality
best_result = max(
    response['results'],
    key=lambda r: r['result']['dataQuality']['overall'] if r['success'] else 0
)

Next Steps

Provider Codes Reference - View all available enrichment codes
Person Provider Codes - Person-specific enrichments
Company Provider Codes - Company-specific enrichments
Execute Risk Matrix - Run risk analysis after enrichment

⌘I

​Overview

​Endpoint

​Authentication

​Request Body

​Response

​Examples

​Execute Single Enrichment

​Execute Multiple Enrichments (Batch)

​Response Example

​Successful Enrichment

​Partial Failure (Some Enrichments Failed)

​Error Responses

​404 Not Found - Entity Not Found

​400 Bad Request - Invalid Integration Code

​401 Unauthorized

​Pricing

​Best Practices

​Automatic Rules Execution

​Use Cases

​Progressive Data Enrichment

​Multi-Provider Strategy

​Next Steps

Overview

Endpoint

Authentication

Request Body

Response

Examples

Execute Single Enrichment

Execute Multiple Enrichments (Batch)

Response Example

Successful Enrichment

Partial Failure (Some Enrichments Failed)

Error Responses

404 Not Found - Entity Not Found

400 Bad Request - Invalid Integration Code

401 Unauthorized

Pricing

Best Practices

Automatic Rules Execution

Use Cases

Progressive Data Enrichment

Multi-Provider Strategy

Next Steps