Skip to main content
POST
/
integration-execution
/
marketplace
/
enrichment-by-external-id
Execute Enrichment by External ID
curl --request POST \
  --url http://api.gu1.ai/integration-execution/marketplace/enrichment-by-external-id \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "<string>",
  "integrationCodes": [
    "<string>"
  ],
  "enrichmentGroupRefs": [
    "<string>"
  ],
  "parameters": {}
}
'
{
  "success": true,
  "entityId": "<string>",
  "externalId": "<string>",
  "results": [
    {}
  ],
  "totalCostCents": 123,
  "totalExecutionTime": 123
}

​
Overview

Executes one or more marketplace enrichment integrations on a specific entity using your own external identifier. This endpoint first looks up the entity by your externalId, then executes the enrichments. It is identical to the by ID endpoint but more convenient when you use your own entity identifiers. Note: enrichmentGroupRefs applies only to this marketplace execution API (and POST .../marketplace/enrichment by entity UUID). Automatic or manual entity creation still uses explicit enrichment codes only, not group slugs.

​
Endpoint

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

​
Authentication

Requires a valid API key in the Authorization header: 
Authorization: Bearer YOUR_API_KEY

​
Request Body

​
externalId
string
required
Your external identifier for the entity (e.g., your customer ID, user ID, etc.)
​
integrationCodes
array<string>
Explicit list of enrichment integration codes to run (same semantics as before). See Integration Provider Codes.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 your organization configured in the Marketplace UI. Each value is a group slug or group UUID. The server replaces each ref with that group’s stored integration codes (in order), then merges any integrationCodes. Each code is still subject to the same orchestrator rules as a direct request (catalog type, org enablement, blocks, etc.).
​
parameters
object
Optional additional parameters to pass to the integrations

​
Response

​
success
boolean
Whether the batch enrichment operation completed successfully
​
entityId
string
The resolved internal UUID of the enriched entity
​
externalId
string
The external ID that was used to look up the 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) - Error code
    • message (string) - Error message
​
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 '{
    "externalId": "customer_12345",
    "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 '{
    "externalId": "customer_12345",
    "integrationCodes": [
      "ar_repet_enrichment",
      "ar_bcra_enrichment",
      "ar_nosis_enrichment"
    ]
  }'

​
Response Example - Successful Enrichment

{
  "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "externalId": "customer_12345",
  "results": [
    {
      "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "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",
  "externalId": "customer_12345",
  "results": [
    {
      "success": true,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "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,
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "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