Skip to main content
POST
/
integration-execution
/
marketplace
/
enrichment
Execute Enrichment by Entity ID
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>"
  ],
  "enrichmentGroupRefs": [
    "<string>"
  ],
  "parameters": {}
}
'
{
  "success": true,
  "entityId": "<string>",
  "results": [
    {}
  ],
  "totalCostCents": 123,
  "totalExecutionTime": 123
}

​
Overview

Executes one or more marketplace enrichment integrations on a specific entity to gather additional data from external providers. This endpoint accepts the entity’s internal UUID and supports batch execution of multiple enrichments in a single request. Note: enrichmentGroupRefs applies only to this marketplace execution API (and POST .../enrichment-by-external-id). Automatic or manual entity creation payloads still take explicit enrichment codes only, not group slugs.

​
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
The UUID of the entity to enrich
​
integrationCodes
array<string>
Explicit list of enrichment integration codes to run (same semantics as before). See Integration Provider Codes.You may send integrationCodes only, enrichmentGroupRefs only, or both. If both are sent, the API expands groups to codes, appends integrationCodes, and deduplicates while keeping first-seen order. At least one of integrationCodes or enrichmentGroupRefs must be non-empty.
​
enrichmentGroupRefs
array<string>
References to enrichment groups defined for your organization under Marketplace (saved list of integration codes). Each item is a group slug or group UUID.Order is preserved: for each ref, the group’s codes are appended in stored order; then any integrationCodes are merged. Expanding groups does not bypass catalog or org rules: each resulting code is still evaluated by the orchestrator (e.g. must be enabled for the org unless a specific fallback path applies, same as when you pass codes directly).
​
parameters
object
Optional additional parameters to pass to the integrations

​
Response

​
success
boolean
Whether the batch enrichment operation completed successfully
​
entityId
string
The UUID of the enriched entity
​
results
array
Array of enrichment results, one for each integration codeEach result contains:
  • success (boolean) - Whether this specific enrichment succeeded
  • enrichmentId (string) - UUID of the enrichment execution record
  • integrationCode (string) - The integration code that was executed
  • integrationName (string) - Human-readable name of the integration
  • result (object) - Enrichment data (only if successful)
    • fieldsEnriched (array) - List of entity fields that were enriched
    • dataQuality (object) - Quality metrics
      • completeness (number) - Data completeness score (0-1)
      • confidence (number) - Confidence score (0-1)
    • summary (string) - Human-readable summary
    • enrichmentData (object) - The actual enrichment data
  • executionTime (number) - Execution time in milliseconds
  • costCents (number) - Cost of this enrichment in cents
  • error (object) - Error details (only if failed)
    • code (string) - Stable error code (e.g. ENRICHMENT_TIMEOUT, INTEGRATION_NOT_ENABLED, HTTP_502)
    • message (string) - Technical error message
    • category (string, optional) - UX grouping: configuration, validation, provider_failure, timeout, auth_error, rate_limit, no_data, system
    • retryable (boolean, optional) - Whether retrying shortly may succeed (timeouts, rate limits, HTTP 5xx)
    • statusCode (number, optional) - Upstream provider HTTP status when applicable
​
totalCostCents
number
Total cost of all enrichments in cents
​
totalExecutionTime
number
Total execution time for all enrichments in milliseconds

​
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": ["ar_repet_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": [
      "ar_repet_enrichment",
      "ar_bcra_enrichment",
      "ar_nosis_enrichment"
    ]
  }'

​
Response Example - Successful Enrichment

{
  "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "success": true,
      "enrichmentId": "enr_abc123def456",
      "integrationCode": "ar_repet_enrichment",
      "integrationName": "Argentina REPET Person Data",
      "result": {
        "fieldsEnriched": [
          "name",
          "taxId",
          "address",
          "legalStatus"
        ],
        "dataQuality": {
          "completeness": 0.95,
          "confidence": 0.92
        },
        "summary": "Successfully enriched person data from REPET",
        "enrichmentData": {
          "name": "María González",
          "taxId": "20-12345678-9",
          "address": {
            "street": "Av. Corrientes 1234",
            "city": "Buenos Aires",
            "province": "CABA",
            "country": "AR"
          },
          "legalStatus": "active"
        }
      },
      "executionTime": 1250,
      "costCents": 50
    }
  ],
  "totalCostCents": 50,
  "totalExecutionTime": 1250
}

​
Response Example - Batch with Mixed Results

{
  "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "results": [
    {
      "success": true,
      "enrichmentId": "enr_abc123",
      "integrationCode": "ar_repet_enrichment",
      "integrationName": "Argentina REPET Person Data",
      "result": {
        "fieldsEnriched": ["name", "taxId"],
        "dataQuality": {
          "completeness": 0.85,
          "confidence": 0.90
        },
        "summary": "Data enriched successfully",
        "enrichmentData": {
          "name": "María González",
          "taxId": "20-12345678-9"
        }
      },
      "executionTime": 1200,
      "costCents": 50
    },
    {
      "success": false,
      "integrationCode": "ar_bcra_enrichment",
      "integrationName": "Argentina BCRA Financial Data",
      "executionTime": 800,
      "costCents": 0,
      "error": {
        "code": "NO_DATA_FOUND",
        "message": "No financial data found for this entity"
      }
    },
    {
      "success": true,
      "enrichmentId": "enr_xyz789",
      "integrationCode": "ar_nosis_enrichment",
      "integrationName": "Argentina Nosis Credit Report",
      "result": {
        "fieldsEnriched": ["creditScore", "riskLevel"],
        "dataQuality": {
          "completeness": 1.0,
          "confidence": 0.95
        },
        "summary": "Credit report retrieved",
        "enrichmentData": {
          "creditScore": 720,
          "riskLevel": "low"
        }
      },
      "executionTime": 1500,
      "costCents": 75
    }
  ],
  "totalCostCents": 125,
  "totalExecutionTime": 3500
}

​
Error Responses

​
404 Entity Not Found

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

​
401 Unauthorized

{
  "success": false,
  "error": {
    "code": "MISSING_ORGANIZATION",
    "message": "Organization ID is required"
  }
}

​
400 Bad Request

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

​
Use Cases

​
KYC Data Enrichment

Enrich a person entity with official government data: 
const enrichmentResult = await fetch(
  'http://api.gu1.ai/integration-execution/marketplace/enrichment',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityId: customerId,
      integrationCodes: [
        'ar_repet_enrichment',  // Official identity data
        'ar_renaper_enrichment' // National registry
      ]
    })
  }
).then(res => res.json());

if (enrichmentResult.success) {
  console.log('Customer data enriched');
  console.log('Total cost:', enrichmentResult.totalCostCents / 100, 'USD');

  // Check each enrichment result
  enrichmentResult.results.forEach(result => {
    if (result.success) {
      console.log(`✓ ${result.integrationName} completed`);
    } else {
      console.log(`✗ ${result.integrationName} failed: ${result.error?.message}`);
    }
  });
}

​
Company Due Diligence

Gather comprehensive company data from multiple sources: 
enrichment_data = requests.post(
    'http://api.gu1.ai/integration-execution/marketplace/enrichment',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'entityId': company_id,
        'integrationCodes': [
            'ar_afip_enrichment',      # Tax authority data
            'ar_bcra_enrichment',      # Central bank data
            'ar_commercial_registry'    # Commercial registry
        ]
    }
).json()

# Process successful enrichments
successful = [r for r in enrichment_data['results'] if r['success']]
failed = [r for r in enrichment_data['results'] if not r['success']]

print(f"Completed: {len(successful)}/{len(enrichment_data['results'])}")
print(f"Total cost: ${enrichment_data['totalCostCents'] / 100:.2f}")

​
Important Notes

  • Batch Execution: Multiple enrichments are executed in parallel for better performance
  • Cost Tracking: Each enrichment’s cost is tracked individually and summed in totalCostCents
  • Partial Success: The batch can succeed even if some individual enrichments fail
  • Automatic Audit: All enrichments are automatically logged in the audit trail
  • Rules Trigger: Successful enrichments trigger the rules engine with enrichment_completed event
  • Idempotency: Running the same enrichment multiple times may return cached results unless forceRefresh is used