Unusual Whales API - Companies endpoints (CompaniesController)

Unusual Whales API - Companies endpoints

Per-ticker fundamentals + corporate-action surface. Five endpoints: profile, dividends, earnings estimates, splits, and earnings-call transcripts. All path-scoped by {ticker}. Read-only.

These are context features, not signal sources. They help frame trades (avoid earnings, respect split dates, know the beta) rather than trigger them. Earnings-call transcripts are the one with non-obvious upside via embeddings/NLP for a future research session.

1. Base contract

Property	Value
Base URL	https://api.unusualwhales.com
Auth	Authorization: Bearer <token> header
Response envelope	{ "data": { ... } }
Status codes	200, 422, 500
Rate limits	Not specified

2. Endpoint matrix

#	Path	Purpose
1	GET /api/companies/{ticker}/profile	Fundamental snapshot (beta, target, CIK, …)
2	GET /api/companies/{ticker}/dividends	Dividend history
3	GET /api/companies/{ticker}/earnings-estimates	Forward earnings estimates
4	GET /api/companies/{ticker}/splits	Stock split history
5	GET /api/companies/{ticker}/transcripts/{quarter}	Earnings call transcript for a given YYYYQ[1-4]

3. GET /api/companies/{ticker}/profile

Static-ish fundamental snapshot.

Response fields:

Field	Type	Description
analyst_target_price	number	Consensus 12mo price target
asset_type	string	E.g. "Common Stock", "ETF"
beta	number	Equity beta (vs broad index)
cik	string	SEC CIK number
country	string	Country of domicile

The docs only show these 5; the live response likely has more (sector, market cap, employee count, etc.) - verify on first real fetch and update this page.

MK3 use. Beta is the relevant field for portfolio framing. For SPY-only hunter, this endpoint is essentially diagnostic - useful when expanding to other tickers.

4. GET /api/companies/{ticker}/dividends

Dividend history.

Response:

{
  "data": {
    "ticker": "AAPL",
    "dividends": [/* per-dividend records, shape not detailed */]
  }
}

The per-record shape isn’t in the docs - expect ex_date, payment_date, record_date, amount fields. Verify on first fetch.

MK3 use. Ex-dividend dates create overnight price gaps. For a 0DTE SPY hunter, SPY’s quarterly dividend distribution dates matter (~mid-Mar, mid-Jun, mid-Sep, mid-Dec). Build a calendar that vetoes trade entry into the ex-div print.

5. GET /api/companies/{ticker}/earnings-estimates

Forward earnings estimates.

Response:

{
  "data": {
    "ticker": "AAPL",
    "estimates": [/* per-estimate records, shape not detailed */]
  }
}

Expected per-record fields: quarter, eps_estimate, eps_actual (if past), revenue_estimate, analyst_count. Verify on first fetch.

MK3 use. For the SPY hunter, irrelevant (SPY doesn’t have earnings). For per-ticker strategies, gate-out the trading day before earnings.

6. GET /api/companies/{ticker}/splits

Stock split history.

Response:

{
  "data": {
    "ticker": "AAPL",
    "splits": [/* per-split records, shape not detailed */]
  }
}

Expected per-record: ex_date, ratio_from, ratio_to, announcement_date. Verify on first fetch.

MK3 use. Historical data corrections - any backtest crossing a split date needs price/contract adjustments. Have this endpoint queryable when wiring the data pipeline. SPY itself has never split.

7. GET /api/companies/{ticker}/transcripts/{quarter}

Earnings call transcript.

Path parameters:

Param	Type	Required	Pattern
ticker	string	yes	Standard equity ticker
quarter	string	yes	^[0-9]{4}Q[1-4]$ e.g. 2024Q1

Response:

{
  "data": {
    "ticker": "AAPL",
    "quarter": "2024Q1",
    "statements": [/* transcript content */]
  }
}

The statements array’s per-row schema isn’t documented. Expect something like [{ speaker, role, text, timestamp }]. Verify on first fetch.

MK3 use. Not in current scope, but highest research upside of the Companies endpoints: feed transcripts into an embedding model, score sentiment against subsequent N-day returns, build a tradeable signal. Future research session, not 0DTE-relevant.

8. Nautilus integration shape

For the SPY hunter scope, only splits and (quarterly) dividends matter for calendar gating. Implementation:

• One-time pull at session start of splits + dividends for SPY.
• Cache in memory; check trade-time against ex-dates.
• No custom data class needed unless we expand to multi-ticker.

profile, earnings-estimates, and transcripts are reference-only at MK3 scope.

9. Known gaps

• Per-record schemas are placeholders in the docs (the dividends[], estimates[], splits[], statements[] arrays contain null). First real fetch needs to update this page with the actual fields.
• No POST/PUT - read-only surface.
• Transcripts only by quarter - no fuzzy search yet.

10. Source URLs

• https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.profile
• https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.dividends
• https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.earnings_estimates
• https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.splits
• https://api.unusualwhales.com/docs/operations/PublicApi.CompaniesController.transcript

uw-api-gex-greeks uw-api-alerts uw-api-commodities