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

# Company

> Company facts, identity, and discovery.

Company facts describe the identity of each issuer in a scenario: name, sector, industry, exchange, CIK, and listing metadata. Identity is grounded in real reference data; everything financial is synthetic. See [Ticker universe](/concepts/ticker-universe).

## Company facts

```http theme={null}
GET /company/facts
```

Returns facts for a single company by `ticker` or `cik`.

| Parameter     | Type   | Required | Description                               |
| ------------- | ------ | -------- | ----------------------------------------- |
| `scenario_id` | string | Yes      | The world to read from.                   |
| `ticker`      | string | No       | Symbol to look up.                        |
| `cik`         | string | No       | CIK to look up (alternative to `ticker`). |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/company/facts?scenario_id=<id>&ticker=AAPL" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.company.facts("AAPL", scenario_id="<id>")
  ```
</CodeGroup>

```json theme={null}
{
  "company_facts": {
    "ticker": "AAPL",
    "name": "Apple Inc.",
    "cik": "0000320193",
    "sector": "Technology",
    "industry": "Consumer Electronics",
    "category": "Operating Company",
    "exchange": "NASDAQ",
    "is_active": true,
    "location": "Cupertino, CA",
    "sic_code": "3571",
    "sic_industry": "Electronic Computers",
    "sic_sector": "Manufacturing",
    "sec_filings_url": "https://.../cik=0000320193"
  }
}
```

Returns `404` if the company is not found in the scenario.

## List companies

```http theme={null}
GET /companies
```

List or search companies in a scenario.

| Parameter     | Type    | Required | Default | Description                                                           |
| ------------- | ------- | -------- | ------- | --------------------------------------------------------------------- |
| `scenario_id` | string  | Yes      | -       | The world to read from.                                               |
| `ticker`      | string  | No       | -       | Filter to a single ticker.                                            |
| `search`      | string  | No       | -       | Free-text search over name, sector, industry, or ticker (≤128 chars). |
| `limit`       | integer | No       | 100     | Page size (max 5000).                                                 |
| `offset`      | integer | No       | 0       | Pagination offset.                                                    |

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/companies?scenario_id=<id>&search=semiconductor&limit=25" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.company.list(scenario_id="<id>", search="semiconductor", limit=25)
  ```
</CodeGroup>

```json theme={null}
{ "companies": [ { "ticker": "NVDA", "name": "NVIDIA Corp.", "sector": "Technology", "...": "..." } ] }
```

## Discovery helpers

List the identifiers actually present in a scenario.

```http theme={null}
GET /company/facts/tickers
```

```json theme={null}
{ "tickers": ["AAPL", "MSFT", "NVDA", "..."] }
```

```http theme={null}
GET /company/facts/ciks
```

```json theme={null}
{ "ciks": ["0000320193", "0000789019", "..."] }
```

Both take only `scenario_id`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -s "https://api.davidhf.com/company/facts/tickers?scenario_id=<id>" \
    -H "X-API-KEY: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  dd.company.tickers(scenario_id="<id>")
  ```
</CodeGroup>