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": {}
}
'

import requests

url = "http://api.gu1.ai/integration-execution/marketplace/enrichment"

payload = {
    "entityId": "<string>",
    "integrationCodes": ["<string>"],
    "enrichmentGroupRefs": ["<string>"],
    "parameters": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityId: '<string>',
    integrationCodes: ['<string>'],
    enrichmentGroupRefs: ['<string>'],
    parameters: {}
  })
};

fetch('http://api.gu1.ai/integration-execution/marketplace/enrichment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/integration-execution/marketplace/enrichment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityId' => '<string>',
    'integrationCodes' => [
        '<string>'
    ],
    'enrichmentGroupRefs' => [
        '<string>'
    ],
    'parameters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/integration-execution/marketplace/enrichment"

	payload := strings.NewReader("{\n  \"entityId\": \"<string>\",\n  \"integrationCodes\": [\n    \"<string>\"\n  ],\n  \"enrichmentGroupRefs\": [\n    \"<string>\"\n  ],\n  \"parameters\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/integration-execution/marketplace/enrichment")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityId\": \"<string>\",\n  \"integrationCodes\": [\n    \"<string>\"\n  ],\n  \"enrichmentGroupRefs\": [\n    \"<string>\"\n  ],\n  \"parameters\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/integration-execution/marketplace/enrichment")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityId\": \"<string>\",\n  \"integrationCodes\": [\n    \"<string>\"\n  ],\n  \"enrichmentGroupRefs\": [\n    \"<string>\"\n  ],\n  \"parameters\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "entityId": "<string>",
  "results": [
    {}
  ],
  "totalCostCents": 123,
  "totalExecutionTime": 123
}

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": {}
}
'

import requests

url = "http://api.gu1.ai/integration-execution/marketplace/enrichment"

payload = {
    "entityId": "<string>",
    "integrationCodes": ["<string>"],
    "enrichmentGroupRefs": ["<string>"],
    "parameters": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entityId: '<string>',
    integrationCodes: ['<string>'],
    enrichmentGroupRefs: ['<string>'],
    parameters: {}
  })
};

fetch('http://api.gu1.ai/integration-execution/marketplace/enrichment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/integration-execution/marketplace/enrichment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entityId' => '<string>',
    'integrationCodes' => [
        '<string>'
    ],
    'enrichmentGroupRefs' => [
        '<string>'
    ],
    'parameters' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/integration-execution/marketplace/enrichment"

	payload := strings.NewReader("{\n  \"entityId\": \"<string>\",\n  \"integrationCodes\": [\n    \"<string>\"\n  ],\n  \"enrichmentGroupRefs\": [\n    \"<string>\"\n  ],\n  \"parameters\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://api.gu1.ai/integration-execution/marketplace/enrichment")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entityId\": \"<string>\",\n  \"integrationCodes\": [\n    \"<string>\"\n  ],\n  \"enrichmentGroupRefs\": [\n    \"<string>\"\n  ],\n  \"parameters\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/integration-execution/marketplace/enrichment")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entityId\": \"<string>\",\n  \"integrationCodes\": [\n    \"<string>\"\n  ],\n  \"enrichmentGroupRefs\": [\n    \"<string>\"\n  ],\n  \"parameters\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

The UUID of the entity to enrich

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.

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

object

Optional additional parameters to pass to the integrations

Response

boolean

Whether the batch enrichment operation completed successfully

string

The UUID of the enriched entity

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

number

Total cost of all enrichments in cents

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"]
  }'

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({
      entityId: '550e8400-e29b-41d4-a716-446655440000',
      integrationCodes: ['ar_repet_enrichment']
    })
  }
);

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

import requests

response = requests.post(
    'http://api.gu1.ai/integration-execution/marketplace/enrichment',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityId': '550e8400-e29b-41d4-a716-446655440000',
        'integrationCodes': ['ar_repet_enrichment']
    }
)

result = response.json()
print(result)

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

Execute Enrichment by External ID - Use your own entity identifier
Get Entity - View enriched entity data
List Integration Providers - Available enrichment codes

Enrichment Overview Execute Enrichment by External ID

⌘I

​Overview

​Endpoint

​Authentication

​Request Body

​Response

​Examples

​Execute Single Enrichment

​Execute Multiple Enrichments (Batch)

​Response Example - Successful Enrichment

​Response Example - Batch with Mixed Results

​Error Responses

​404 Entity Not Found

​401 Unauthorized

​400 Bad Request

​Use Cases

​KYC Data Enrichment

​Company Due Diligence

​Important Notes

​Related Endpoints