> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Note>
  This route lives under **`/integration-execution`**. It uses the same **integration codes** as the rest of the Marketplace (see [Shared provider codes](/en/api-reference/integrations/shared-provider-codes), [Person provider codes](/en/api-reference/integrations/person-provider-codes), and [Company provider codes](/en/api-reference/integrations/company-provider-codes)).\
  Execution requires permission to **run enrichments** (same family as `POST /integration-execution/marketplace/enrichment`).
</Note>

<Warning>
  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.
</Warning>

## 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](/en/api-reference/integrations/headless-executions) and [Get headless execution by id](/en/api-reference/integrations/headless-executions-item).

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

<ParamField query="cached" type="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`).
</ParamField>

## Request Body

<ParamField body="integrationCode" type="string" required>
  Marketplace integration code (e.g. `br_cpfcnpj_complete_company_enrichment`).
</ParamField>

<ParamField body="country" type="string" required>
  ISO 3166-1 alpha-2 country code (two letters, case-insensitive; stored uppercase).
</ParamField>

<ParamField body="type" type="string" required>
  Either `person` or `company`. Must match what the integration expects for the country (wrong type can yield no matching provider).
</ParamField>

<ParamField body="taxId" type="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.
</ParamField>

<ParamField body="name" type="string">
  Optional display / resolution name. At least one of **`taxId`** or **`name`** is required.
</ParamField>

<ParamField body="parameters" type="object">
  Optional provider-specific parameters (defaults to `{}`).
</ParamField>

## Success response (HTTP 200)

When `enrichmentSuccess` is `true`, the body includes:

<ResponseField name="success" type="boolean">Always `true` for a handled request.</ResponseField>
<ResponseField name="cached" type="boolean">Whether the result came from cache.</ResponseField>
<ResponseField name="integrationCode" type="string">Echo of the code executed.</ResponseField>
<ResponseField name="country" type="string">Echo of country.</ResponseField>
<ResponseField name="type" type="string">`person` or `company`.</ResponseField>
<ResponseField name="enrichmentSuccess" type="boolean">`true` when normalization produced consolidated data.</ResponseField>

<ResponseField name="result" type="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).
</ResponseField>

<ResponseField name="errors" type="array">Usually empty on success.</ResponseField>
<ResponseField name="totalCostCents" type="number">Total charged cost in cents when applicable.</ResponseField>
<ResponseField name="executionTimeMs" type="number">Wall time for the run.</ResponseField>

<ResponseField name="probeEntityId" type="string">
  Present on **200** success: correlation / in-memory trace id (not an `entities.id` FK).
</ResponseField>

<ResponseField name="billing" type="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.
</ResponseField>

## 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

```bash theme={null}
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": {}
  }'
```