> ## 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.

# Execute Enrichment by External ID

> Execute marketplace enrichment integrations on an entity using your own external identifier — using gu1 marketplace providers for KYC, KYB, and PEP data.

## 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:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Request Body

<ParamField body="externalId" type="string" required>
  Your external identifier for the entity (e.g., your customer ID, user ID, etc.)
</ParamField>

<ParamField body="integrationCodes" type="array<string>">
  Explicit list of enrichment integration codes to run (same semantics as before). See [Integration Provider Codes](/en/api-reference/integrations/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.
</ParamField>

<ParamField body="enrichmentGroupRefs" type="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.).
</ParamField>

<ParamField body="parameters" type="object">
  Optional additional parameters to pass to the integrations
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Whether the batch enrichment operation completed successfully
</ResponseField>

<ResponseField name="entityId" type="string">
  The resolved internal UUID of the enriched entity
</ResponseField>

<ResponseField name="externalId" type="string">
  The external ID that was used to look up the entity
</ResponseField>

<ResponseField name="results" type="array">
  Array of enrichment results, one for each integration code

  Each 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
</ResponseField>

<ResponseField name="totalCostCents" type="number">
  Total cost of all enrichments in cents
</ResponseField>

<ResponseField name="totalExecutionTime" type="number">
  Total execution time for all enrichments in milliseconds
</ResponseField>

## Examples

### Execute Single Enrichment

<CodeGroup>
  ```bash cURL theme={null}
  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"]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = 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({
        externalId: 'customer_12345',
        integrationCodes: ['ar_repet_enrichment']
      })
    }
  );

  const result = await response.json();
  console.log(result);
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'http://api.gu1.ai/integration-execution/marketplace/enrichment',
      headers={
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
      },
      json={
          'externalId': 'customer_12345',
          'integrationCodes': ['ar_repet_enrichment']
      }
  )

  result = response.json()
  print(result)
  ```
</CodeGroup>

### Execute Multiple Enrichments (Batch)

```bash theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

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

### 401 Unauthorized

```json theme={null}
{
  "success": false,
  "error": {
    "code": "MISSING_ORGANIZATION",
    "message": "Organization ID is required"
  }
}
```

### 400 Bad Request

```json theme={null}
{
  "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:

```javascript theme={null}
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:

```python theme={null}
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

## Related Endpoints

* [Execute Enrichment by External ID](/en/api-reference/enrichment/execute-by-external-id) - Use your own entity identifier
* [Get Entity](/api-reference/entities/get) - View enriched entity data
* [List Integration Providers](/en/api-reference/integrations/provider-codes) - Available enrichment codes