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": {}
}
'import requests
url = "http://api.gu1.ai/integration-execution/marketplace/enrichment"
payload = {
"entityId": "<string>",
"integrationCodes": ["<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>'], 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>'
],
'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 \"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 \"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 \"parameters\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"results": [
{}
],
"totalCostCents": 123,
"totalExecutionTime": 123,
"rulesResult": {},
"rulesExecutionSummary": {}
}Execute Enrichment
Execute data enrichment integrations on entities (companies or persons) — using the gu1 risk scoring engine with configurable triggers.
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": {}
}
'import requests
url = "http://api.gu1.ai/integration-execution/marketplace/enrichment"
payload = {
"entityId": "<string>",
"integrationCodes": ["<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>'], 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>'
],
'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 \"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 \"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 \"parameters\": {}\n}"
response = http.request(request)
puts response.read_body{
"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
string
required
UUID of the entity (company or person) to enrich
array<string>
required
Array of enrichment integration codes to execute. See Provider Codes Reference for available codes.At least one integration code is required.
object
Optional additional parameters for the integrations (default:
{})Response
boolean
Whether all enrichments succeeded
array<object>
Array of individual enrichment results. Each result contains:
success(boolean) - Whether this enrichment succeededenrichmentId(string) - ID for viewing enrichment detailsintegrationCode(string) - The integration code that was executedresult(object) - Enrichment result data:fieldsEnriched(array<string>) - List of fields that were enricheddataQuality(object) - Data quality metricssummary(string) - Human-readable summaryenrichmentData(object) - The enriched data
executionTime(number) - Execution time in millisecondscostCents(number) - Cost in centserror(object, optional) - Error details if failed
number
Total cost for all enrichments in cents
number
Total execution time for all enrichments in milliseconds
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.
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"]
}'
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: ['br_cpfcnpj_complete_person_enrichment']
})
}
);
const data = await response.json();
console.log(`Enriched ${data.results[0].result.fieldsEnriched.length} fields`);
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': ['br_cpfcnpj_complete_person_enrichment']
}
)
data = response.json()
print(f"Enriched {len(data['results'][0]['result']['fieldsEnriched'])} fields")
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"
]
}'
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: [
'br_cpfcnpj_complete_person_enrichment',
'br_serpro_cpf_status_enrichment',
'global_clear_sale_person_enrichment'
]
})
}
);
const data = await response.json();
console.log(`Total cost: ${data.totalCostCents / 100} tokens`);
console.log(`${data.results.filter(r => r.success).length} of ${data.results.length} succeeded`);
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': [
'br_cpfcnpj_complete_person_enrichment',
'br_serpro_cpf_status_enrichment',
'global_clear_sale_person_enrichment'
]
}
)
data = response.json()
successes = sum(1 for r in data['results'] if r['success'])
print(f"{successes} of {len(data['results'])} enrichments succeeded")
print(f"Total cost: {data['totalCostCents'] / 100} tokens")
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
successfields in results array - Cost Management: Monitor
totalCostCentsto track usage - Provider Selection: Choose enrichments based on your entity’s country and required fields
- View Details: Use the
enrichmentIdto view complete enrichment details later
Automatic Rules Execution
When enrichments succeed, the rules engine may automatically execute based on your risk matrix configuration. TherulesResult 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
Was this page helpful?