Execute marketplace enrichment without entity
API Reference
Execute marketplace enrichment without entity
Run a single marketplace enrichment from tax ID and/or name without persisting an entity; optional cache-only mode. See request schema, response codes.
POST
Execute marketplace enrichment without entity
This route lives under
Execution requires permission to run enrichments (same family as
/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).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 givenintegrationCode, 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)
WhenenrichmentSuccess 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
WhenenrichmentSuccess 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.