Skip to main content
POST
Execute marketplace enrichment without entity
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

Query Parameters

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

string
required
Marketplace integration code (e.g. br_cpfcnpj_complete_company_enrichment).
string
required
ISO 3166-1 alpha-2 country code (two letters, case-insensitive; stored uppercase).
string
required
Either person or company. Must match what the integration expects for the country (wrong type can yield no matching provider).
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.
string
Optional display / resolution name. At least one of taxId or name is required.
object
Optional provider-specific parameters (defaults to {}).

Success response (HTTP 200)

When enrichmentSuccess is true, the body includes:
boolean
Always true for a handled request.
boolean
Whether the result came from cache.
string
Echo of the code executed.
string
Echo of country.
string
person or company.
boolean
true when normalization produced consolidated data.
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).
array
Usually empty on success.
number
Total charged cost in cents when applicable.
number
Wall time for the run.
string
Present on 200 success: correlation / in-memory trace id (not an entities.id FK).
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