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

# POST /enrich

> Firmographics + headline insight + SWOT + competitors + people + events.

## Use case

After resolving an entity with [`/validate`](/endpoints/validate), call `/enrich` for the full BETA picture: firmographics, market cap, headline insight, optionally SWOT + competitors + priorities (`include: ['intelligence']`), events during a tenure window (`include: ['events']` with `tenure`), key people inline (`include: ['people']`), or historical intelligence snapshots (`include: ['intelligence_history']`).

## Request

<ParamField body="company" type="string" required>
  Company name or canonical entity key. 2–200 characters.
</ParamField>

<ParamField body="tenure" type="object">
  When present, scopes `events` to a window: `{ "start": "YYYY-MM", "end": "YYYY-MM" }`.
</ParamField>

<ParamField body="include" type="array">
  Subset of `["events", "people", "intelligence", "intelligence_history"]`.
</ParamField>

## Response

<ResponseField name="verified" type="boolean">Same semantics as [`/validate`](/endpoints/validate).</ResponseField>
<ResponseField name="confidence" type="number">Entity-match confidence (0–1).</ResponseField>

<ResponseField name="entity" type="object">
  Canonical entity. Extends [`/validate`'s entity](/endpoints/validate) with `exchange`, `headquarters`, `founded`, `employees`, `description`.
</ResponseField>

<ResponseField name="scale" type="object">
  Where available: `marketCap` (formatted, e.g., `"$1.2T"`), `revenueRange` (e.g., `"$10B+"`).
</ResponseField>

<ResponseField name="context" type="string | null">
  Display summary — synthesized 2–4 paragraph briefing on the company. News-corroborated, source-cited inline as `[N]` footnote markers.
</ResponseField>

<ResponseField name="headlineInsight" type="string | null">
  Short (\~1 sentence) insight surfaced from the latest synthesis run.
</ResponseField>

<ResponseField name="events" type="array">
  Material events (SEC 8-K filings) — populated when `include: ['events']` and `tenure` is provided.
</ResponseField>

<ResponseField name="people" type="array">
  Indexed people — populated when `include: ['people']`. See [`/people`](/endpoints/people) for full schema.
</ResponseField>

<ResponseField name="intelligence" type="object | null">
  SWOT, competitors, priorities, changelog, confidence — populated when `include: ['intelligence']`.
</ResponseField>

<ResponseField name="intelligence_history" type="object | null">
  Temporal snapshots (up to 30) — populated when `include: ['intelligence_history']`.
</ResponseField>

<ResponseField name="meta" type="object">
  `enrichedAt` (ISO datetime), `sources` (array of structured datasets used), `resolution` (per Citation Contract), `costEstimate` (USD).
</ResponseField>

## Code samples

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.getbeta.io/api/v1/enrich \
    -H "Authorization: Bearer $BETA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"company": "Stripe", "include": ["events"]}'
  ```

  ```javascript JavaScript theme={null}
  const res = await fetch('https://api.getbeta.io/api/v1/enrich', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.BETA_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      company: 'Stripe',
      include: ['events']
    })
  });
  const data = await res.json();
  ```

  ```python Python theme={null}
  import os, requests
  res = requests.post(
      'https://api.getbeta.io/api/v1/enrich',
      headers={'Authorization': f'Bearer {os.environ["BETA_API_KEY"]}'},
      json={'company': 'Stripe', 'include': ['events']}
  )
  data = res.json()
  ```
</CodeGroup>

## Live response

```json theme={null}
{
  "verified": true,
  "confidence": 1,
  "entity": {
    "key": "stripe",
    "name": "Stripe Inc.",
    "type": "private_company",
    "ticker": null,
    "industry": "financial_services",
    "publicUrl": "https://getbeta.io/company/stripe"
  },
  "scale": {},
  "context": "Stripe published its 2025 annual letter and announced a tender offer to provide liquidity to current and former employees [11]. The company completed its acquisition of Metronome, expanding its platform capabilities [6]. Stripe powered Higgsfield's global expansion and marketplace launch, demonstrating continued adoption across commerce platforms [5]...",
  "events": [],
  "people": [],
  "meta": {
    "enrichedAt": "2026-05-20T03:49:30.379Z",
    "sources": ["entity_resolution", "entity_summaries"],
    "resolution": { "source": "curated", "confidence": 1 },
    "costEstimate": 0.008
  }
}
```

<Note>
  Private companies (like Stripe) often have no SEC events — `events: []` is expected, not an error. Public companies return populated arrays when `include: ['events']` is set.
</Note>

## Errors

| Status | Body                                                                                         | When                      |
| ------ | -------------------------------------------------------------------------------------------- | ------------------------- |
| `400`  | `{"error": "Ambiguous company name", "code": "NEEDS_DISAMBIGUATION", "alternatives": [...]}` | Multiple entities matched |
| `404`  | `{"verified": false, "error": "Company not found", "code": "NOT_FOUND"}`                     | No entity resolved        |
| Other  | See [`/validate`](/endpoints/validate#errors) for the standard set                           |                           |

## Citation pointer

See [Citation Contract](/citation-contract) for how `meta.sources[]`, `intelligence.competitors[*].source`, and the `[N]` footnote markers in `context` are populated.