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

# Display company data on your site

> Embed Sacra company data, valuation charts, and research documents into your application

The Sacra API provides two ways to display company data on your site: **ready-to-use embeds** that return drop-in HTML iframes, and **raw JSON endpoints** for building fully custom UIs.

## Embeds

Embed endpoints return an `embed_html` string containing a styled `<iframe>` you can insert directly into any page. Every embed accepts optional `height` and `width` parameters (in pixels).

### Company data summary

A pre-built summary card with key company metrics.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/embed/company-data-summary/?company_domain=stripe.com"
```

```json theme={null}
{
  "status": "success",
  "data": {
    "embed_html": "<iframe src=\"...\" height=\"840\" width=\"600\"></iframe>"
  }
}
```

Drop the HTML into your page:

```html theme={null}
<div id="sacra-summary"></div>

<script>
  fetch("https://sacra.com/api/v1/embed/company-data-summary/?company_domain=stripe.com", {
    headers: { "Authorization": "Token YOUR_API_KEY" }
  })
    .then(res => res.json())
    .then(data => {
      document.getElementById("sacra-summary").innerHTML = data.data.embed_html;
    });
</script>
```

<Tip>Pass `height` and `width` query parameters to control the iframe dimensions, e.g. `?company_domain=stripe.com&height=600&width=800`.</Tip>

### Valuation chart

An interactive chart showing a company's valuation history.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/embed/company-data-valuation-chart/?company_domain=stripe.com"
```

### Valuation table

A tabular view of valuation data points.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/embed/company-data-valuation-table/?company_domain=stripe.com"
```

### Document PDF

Embed a Sacra research document as a PDF viewer.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/embed/document-pdfs/?document_slug=stripe-revenue"
```

<Note>
  All embed endpoints identify companies by **one of** `company_slug`, `company_domain`, or `company_id`. The document PDF embed uses `document_slug` instead.
</Note>

***

## Build a custom UI with JSON data

If you need full control over presentation, use the JSON endpoints to fetch raw data and render it yourself.

### Fetch company profile

The `/api/v1/companies/` endpoint returns the full [company profile](/concepts/companies) including financials, milestones, and metadata.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/companies/?company_domain=stripe.com"
```

The response wraps the company object inside a `company` key:

```json theme={null}
{
  "company": {
    "id": 112,
    "slug": "stripe",
    "name": "Stripe",
    "domain": "stripe.com",
    "is_active": true,
    "type": "private",
    "logo": { ... },
    "social": [
      { "url": "https://twitter.com/stripe", "type": "twitter" }
    ],
    "founding_year": 2010,
    "headquarters": { ... },
    "description": "...",
    "financials": [
      { "name": "latest_estimated_revenue", "value": 6900000000, "date": "2025-12-30" },
      { "name": "latest_estimated_valuation", "value": 91500000000, "date": "2025-02-26" },
      { "name": "total_estimated_funding", "value": 9800000000, "date": "2025-05-05" }
    ],
    "milestones": [ { "id": "1", "type": "...", "date": "...", "label": "...", "description": "..." } ],
    "listings": [ { "id": "1", "type": "...", "venue": "...", "ticker": "..." } ],
    "categories": [
      { "id": 12, "name": "fintech", "slug": "fintech" },
      { "id": 11, "name": "b2b", "slug": "b2b" }
    ],
    "documents": [ ... ],
    "company_datasets": [ ... ]
  }
}
```

Each entry in `financials` has a snake\_case `name`, a numeric `value`, and a `date`.

### Fetch financial metrics

The `/api/v1/metrics/` endpoint returns detailed [metric observations](/concepts/revenue#metric-observations) with citations.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/metrics/?company_domain=stripe.com"
```

You can filter by metric type and date range:

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/metrics/?company_domain=stripe.com&metric_base=revenue&measurement_scenario=historical"
```

The response wraps results inside a `metrics` key:

```json theme={null}
{
  "metrics": [
    {
      "metric_id": "35c57075-5f39-46ff-9379-d8408ad3a547",
      "metric_definition": {
        "base": "run_rate_revenue",
        "view": "value",
        "base_forward": "year",
        "base_period": null,
        "growth_period": null,
        "growth_period_length": null
      },
      "measurement": {
        "scenario": "historical",
        "end_date": "2025-01-31",
        "custom_start_date": null,
        "comparison_window_end_date": null,
        "comparison_window_custom_start_date": null,
        "type": "equals",
        "unit_kind": "currency",
        "currency_code": "USD",
        "amount": 500000000,
        "low": null,
        "high": null,
        "scope_name": null,
        "scope_type": null,
        "status": "Active"
      },
      "company": { "id": "112", "slug": "stripe", "domain": "stripe.com" },
      "citations": {
        "summary": { "count": 1 },
        "sources": [ { "url": "https://...", "quote": "..." } ]
      },
      "created_at": "2026-02-25T20:17:24.715380+00:00",
      "updated_at": "2026-02-26T20:27:14.216043+00:00"
    }
  ],
  "pagination": { ... },
  "meta": { ... }
}
```

Key fields to note:

* **`metric_definition.base`** — the metric type (e.g. `revenue`, `run_rate_revenue`, `recurring_revenue`)
* **`metric_definition.view`** — either `value` or `growth`
* **`measurement.amount`** — the metric value
* **`measurement.end_date`** — the date the metric applies to
* **`measurement.scenario`** — typically `historical` or `projection`

<Warning>
  When `metric_definition.view` is `"growth"`, the `amount` field is a percentage — even if `unit_kind` says `"currency"`. Always check the `view` field before interpreting `amount`.
</Warning>

<Note>
  Some metrics return `amount: null` with `low` and `high` range values instead of a single point estimate.
</Note>

### Fetch funding events

The `/api/v1/events/` endpoint returns aggregated [company events](/concepts/events) including funding rounds, secondary transactions, milestones, and corporate actions.

```bash theme={null}
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://sacra.com/api/v1/events/?company_domain=stripe.com&types=funding-round"
```

Filter by event type using the `types` parameter. Supported values: `funding-round`, `secondary-transaction`, `company-milestone`, `corporate-action`.

<Note>
  The `types` query parameter uses kebab-case, while the `event_type` field in the response uses snake\_case (e.g. `funding_round`).
</Note>

The response wraps results inside an `events` key:

```json theme={null}
{
  "events": [
    {
      "event_id": "fr_561d3001-52d0-4dfc-b2f2-1b2ed5d9e22a",
      "event_type": "funding_round",
      "event_subtype": "series_a",
      "event_name": "Series A (2026)",
      "event_date": "2026-02-23",
      "event_status": "closed",
      "event_last_updated_at": "2026-02-24T18:05:55.786756+00:00",
      "company": { "id": "112", "slug": "stripe", "domain": "stripe.com" },
      "data": {
        "id": "561d3001-52d0-4dfc-b2f2-1b2ed5d9e22a",
        "name": "Series A (2026)",
        "round_type": "series_a",
        "amount_raised": "16600000.00",
        "updated_at": "2026-02-24T18:05:55.786756+00:00"
      }
    }
  ],
  "pagination": { ... },
  "meta": { ... }
}
```

Each event has top-level metadata (`event_type`, `event_name`, `event_date`, `event_status`) and a `data` object with type-specific details like `amount_raised` for funding rounds.

***

## Example: React company card

Here's a complete example building a company card component with React. The component fetches data through your own backend proxy to keep the API token server-side.

```jsx theme={null}
import { useState, useEffect } from "react";

function CompanyCard({ domain }) {
  const [company, setCompany] = useState(null);

  useEffect(() => {
    fetch(`/api/sacra/company?domain=${domain}`)
      .then((res) => res.json())
      .then((data) => setCompany(data.company));
  }, [domain]);

  if (!company) return <div>Loading...</div>;

  const findFinancial = (name) =>
    company.financials?.find((f) => f.name === name);

  const revenue = findFinancial("latest_estimated_revenue");
  const valuation = findFinancial("latest_estimated_valuation");

  return (
    <div className="company-card">
      <h2>{company.name}</h2>
      <p>{company.description}</p>

      <dl>
        {revenue && (
          <>
            <dt>Revenue</dt>
            <dd>${(revenue.value / 1e9).toFixed(1)}B</dd>
          </>
        )}
        {valuation && (
          <>
            <dt>Valuation</dt>
            <dd>${(valuation.value / 1e9).toFixed(1)}B</dd>
          </>
        )}
      </dl>
    </div>
  );
}
```

The `/api/sacra/company` route is a backend proxy you create to forward requests to the Sacra API. A minimal Express example:

```js theme={null}
app.get("/api/sacra/company", async (req, res) => {
  const response = await fetch(
    `https://sacra.com/api/v1/companies/?company_domain=${req.query.domain}`,
    { headers: { Authorization: `Token ${process.env.SACRA_API_KEY}` } }
  );
  res.json(await response.json());
});
```

<Warning>
  Never expose your API token in client-side code shipped to end users. Proxy requests through your own backend and keep the token server-side.
</Warning>

***

## Embed reference

| Endpoint                                      | Method | Identifies by                                  | Returns                |
| --------------------------------------------- | ------ | ---------------------------------------------- | ---------------------- |
| `/api/v1/embed/company-data-summary/`         | GET    | company\_slug, company\_domain, or company\_id | Summary card iframe    |
| `/api/v1/embed/company-data-valuation-chart/` | GET    | company\_slug, company\_domain, or company\_id | Valuation chart iframe |
| `/api/v1/embed/company-data-valuation-table/` | GET    | company\_slug, company\_domain, or company\_id | Valuation table iframe |
| `/api/v1/embed/document-pdfs/`                | GET    | document\_slug                                 | PDF viewer iframe      |
| `/api/v1/embed/charts/`                       | PUT    | dataset\_id (in request body)                  | Custom chart iframe    |