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

# Ground a customer email

> Validate → enrich → cite. The standard wedge pattern.

## Scenario

Your agent receives a customer email mentioning a company you don't know much about. You need firmographics and recent priorities to write an informed response — and you want to cite where the information came from.

## Pattern

Three calls:

1. **`/validate`** — confirm the company exists in BETA, get the canonical entity key.
2. **`/enrich`** — pull firmographics + headline insight + sources used.
3. **Render with citations** — surface `meta.sources[]` and `sources_cited` count to your reader.

## Implementation

```javascript theme={null}
async function groundEmail(companyName) {
  const headers = {
    'Authorization': `Bearer ${process.env.BETA_API_KEY}`,
    'Content-Type': 'application/json'
  };

  // 1. Validate
  const v = await fetch('https://api.getbeta.io/api/v1/validate', {
    method: 'POST',
    headers,
    body: JSON.stringify({ company: companyName })
  }).then(r => r.json());

  if (!v.verified) {
    if (v.needsDisambiguation) {
      // Ask the user to pick from v.alternatives
      return { status: 'ambiguous', alternatives: v.alternatives };
    }
    return { status: 'unknown', message: v.message };
  }

  // 2. Enrich
  const e = await fetch('https://api.getbeta.io/api/v1/enrich', {
    method: 'POST',
    headers,
    body: JSON.stringify({
      company: v.entity.key,
      include: ['intelligence']
    })
  }).then(r => r.json());

  // 3. Return with citation block
  return {
    status: 'ok',
    summary: e.headlineInsight,
    detail: e.context,
    sources_used: e.meta.sources,
    article_count: e.sources_cited,
    confidence: e.confidence,
    audit: {
      resolution_source: e.meta.resolution.source,
      snapshot_at: e.meta.enrichedAt
    }
  };
}
```

## Why this pattern

* **`/validate` first** filters unknown / ambiguous inputs before paying for `/enrich`. Avoids 404s and saves a billable call.
* **`include: ['intelligence']`** pulls the synthesized SWOT + priorities + competitors, not just firmographics.
* **Returning `sources_used` + `article_count`** makes the response auditable. Surface this in your UI.

## What to do with `confidence`

| Confidence  | Action                                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `> 0.9`     | Surface the answer with full confidence                                                                                        |
| `0.7 – 0.9` | Surface with a "based on BETA's curated entity registry" caveat                                                                |
| `< 0.7`     | Route to a human reviewer or ask the user to confirm the entity (likely `resolution.source: 'discovered'` or `'sec_fallback'`) |

See [Citation Contract → Drop-in patterns](/citation-contract#drop-in-patterns) for the full trust pattern.