Skip to main content
POST
/
integration-execution
/
execute-without-entity
Execute marketplace enrichment without entity
curl --request POST \
  --url http://api.gu1.ai/integration-execution/execute-without-entity \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "integrationCode": "<string>",
  "country": "<string>",
  "type": "<string>",
  "taxId": "<string>",
  "name": "<string>",
  "parameters": {}
}
'
{
  "success": true,
  "cached": true,
  "integrationCode": "<string>",
  "country": "<string>",
  "type": "<string>",
  "enrichmentSuccess": true,
  "result": {},
  "errors": [
    {}
  ],
  "totalCostCents": 123,
  "executionTimeMs": 123,
  "probeEntityId": "<string>",
  "billing": {}
}
This route lives under /integration-execution. It uses the same integration codes as the rest of the Marketplace (see Shared provider codes, Person provider codes, and Company provider codes).
Execution requires permission to run enrichments (same family as POST /integration-execution/marketplace/enrichment).
Headless runs do not create or update rows in entities, normalized_enrichment, or entity-scoped enrichment audit tables. They append read-only audit (headless_enrichment_execution_audit) and may write optional cache (headless_enrichment_cache) for successful responses.

​
Overview

Use this endpoint when you need one enrichment resolved from tax ID and/or name plus country and entity type, without registering a Person or Company in Gu1 first. Related read-only endpoints: List headless executions and Get headless execution by id. Runs the universal provider for the given integrationCode, normalizes the result in memory, applies billing when applicable, and records one audit row.

​
URL

POST https://api.gu1.ai/integration-execution/execute-without-entity

​
Query Parameters

​
cached
boolean
default:"false"
If true or 1, the API only returns a previously cached successful payload for the same inputs (same org, integration, country, type, tax/name, parameters hash). No provider call and no token spend. If there is no cache hit, responds with 404 (CACHE_MISS).

​
Request Body

​
integrationCode
string
required
Marketplace integration code (e.g. br_cpfcnpj_complete_company_enrichment).
​
country
string
required
ISO 3166-1 alpha-2 country code (two letters, case-insensitive; stored uppercase).
​
type
string
required
Either person or company. Must match what the integration expects for the country (wrong type can yield no matching provider).
​
taxId
string
Optional. When provided, it is validated and normalized for the given country and type. At least one of taxId or name (after trim) is required.
​
name
string
Optional display / resolution name. At least one of taxId or name is required.
​
parameters
object
Optional provider-specific parameters (defaults to {}).

​
Success response (HTTP 200)

When enrichmentSuccess is true, the body includes:
​
success
boolean
Always true for a handled request.
​
cached
boolean
Whether the result came from cache.
​
integrationCode
string
Echo of the code executed.
​
country
string
Echo of country.
​
type
string
person or company.
​
enrichmentSuccess
boolean
true when normalization produced consolidated data.
​
result
object
Present when normalization succeeded. Contains raw and mapped: each is an object keyed by integration code (provider raw branch and canonical mapped fields; same family as entity-scoped marketplace enrichments).
​
errors
array
Usually empty on success.
​
totalCostCents
number
Total charged cost in cents when applicable.
​
executionTimeMs
number
Wall time for the run.
​
probeEntityId
string
Present on 200 success: correlation / in-memory trace id (not an entities.id FK).
​
billing
object
tokensSpent and balanceRemainingCents only. costCents is not returned inside billing (it remains for internal use and is stored on the audit row). Use root totalCostCents when you need the charged amount for the attempt in cents.

​
Failure responses

When enrichmentSuccess is false but the HTTP request is still accepted, the API returns 400 if no provider matches the context (e.g. wrong type for the integration), or 422 for provider execution / normalization failures. The JSON body still includes errors, billing (same public billing shape), totalCostCents, etc. Other errors: 403 (integration not enabled), 404 (CACHE_MISS when cached=true), 402 insufficient balance, 4xx validation from Zod.

​
Example

curl -sS -X POST 'https://api.gu1.ai/integration-execution/execute-without-entity' \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationCode": "br_bdc_basic_data_enrichment",
    "country": "BR",
    "type": "person",
    "taxId": "12345678909",
    "parameters": {}
  }'