REST API Documentation

Base URL

Authentication

Every request needs your API key in the Authorization header:

Authorization: Api-Key YOUR_API_KEY

First call in 30 seconds:

curl -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://dividendhunting.com/core/api/stocks/?country=US&yield_min=3"

The API is a Hunter feature. Your subscription is checked on every single request, not just when the key is created. If a Hunter subscription lapses, the key stops working immediately, and it starts working again the moment the subscription is renewed.

New accounts get full Hunter-level access during the free trial so you can build and test your integration before paying, just with tighter limits. When the trial ends, API access ends with it unless you are on Hunter. Compare plans here.

Two kinds of limits protect the service. They are independent, and both apply.

1. Request throttling

Hunter: 30 requests per minute and 500 per day. Trial: 6 per minute and 100 per day. Go over and you get 429 Too Many Requests with a Retry-After header. Wait, then continue. Nothing bad happens.

2. Daily extraction budget

Each resource (stocks, ETFs, dividends) has a daily row budget: 1,000 rows per day on Hunter, 200 on trial. Every row the API returns counts against it. The counter resets at midnight.

Every list endpoint returns 10 results per page. That size is fixed: there is no page_size parameter, and asking for one is silently ignored. Use ?page=N to move through results.

{
  "count": 1432,
  "next": "https://dividendhunting.com/core/api/stocks/?country=US&page=3",
  "previous": "https://dividendhunting.com/core/api/stocks/?country=US&page=1",
  "results": [ ... 10 objects ... ]
}

Tip: filter first, paginate second. The filters below exist so you never need to walk the full dataset, which would burn your daily row budget anyway.

Active, dividend-relevant stocks with prices, dividend profile and our proprietary recovery and prediction metrics (recovery rate, hunting score, prediction confidence, and more).

Filters

Example

curl -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://dividendhunting.com/core/api/stocks/?exchange=NYSE&yield_min=4&market_cap_min=1000000000"

{
  "count": 87,
  "next": "https://dividendhunting.com/core/api/stocks/?exchange=NYSE&yield_min=4&market_cap_min=1000000000&page=2",
  "previous": null,
  "results": [
    {
      "id": 1042,
      "symbol": "T",
      "name": "AT&T Inc.",
      "isin": "US00206R1023",
      "exchange": "NYSE",
      "country": "US",
      "region": "North America",
      "currency": "USD",
      "price": "27.1300",
      "dividend_yield": "4.0900",
      "dividend_yield_ttm": "4.2100",
      "display_ex_date": "2026-07-09",
      "dividend_frequency": "Quarterly",
      "recovery_rate": "78.4000",
      "hunting_score": "12.50",
      "predicted_hunting_score": "14.20",
      "prediction_confidence": 0.83,
      "market_cap": 194500000000,
      "pe_ratio": "11.20",
      "...": "..."
    }
  ]
}

Same shape and metrics as stocks, with ETF-specific fields instead of fundamentals: expense ratio, net assets, asset class, focus, strategy, brand and index tracked.

Filters

All the shared stock filters above (symbol, isin, exchange, country, region, currency, ex_date*, yield_min/max, volume_min/max, dividend_frequency, pays_dividends) plus:

Example

curl -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://dividendhunting.com/core/api/etfs/?focus=Dividend&expense_ratio_max=0.4"

Individual dividend events: the timeline (ex-date, record date, payment date), the payout, the AI prediction made before the ex-date, and the graded result once the event completes. Sorted newest ex-date first.

Look up events by isin directly, or by symbol (optionally narrowed with exchange); the symbol resolves through active stocks and ETFs to its ISIN.

Filters

Example: upcoming high-probability events

curl -H "Authorization: Api-Key YOUR_API_KEY" \
  "https://dividendhunting.com/core/api/dividends/?ex_date_after=2026-06-12&probability_min=0.85"

{
  "count": 23,
  "next": "...",
  "previous": null,
  "results": [
    {
      "id": "0b9f9a3e-7c2d-4f6a-9f1e-2d3c4b5a6978",
      "isin": "US00206R1023",
      "ex_date": "2026-07-09",
      "record_date": "2026-07-09",
      "payment_date": "2026-08-01",
      "amount": "0.277500",
      "event_yield": "1.0200",
      "probability": 0.91,
      "predicted_is_same_day": true,
      "prediction_confidence": 0.86,
      "predicted_days_to_recover": "0.0",
      "predicted_hunting_score": "310.50",
      "prediction_result": null,
      "total_days_to_recover": null,
      "event_status": "IN_PROGRESS",
      "...": "..."
    }
  ]
}

Reference data, handy for building filter dropdowns and for valid country / exchange values. Both include how many stocks and ETFs we cover there.

• /countries/ supports ?region=Europe, detail at /countries/US/
• /exchanges/ supports ?country=US, detail at /exchanges/NYSE/

{
  "code": "NYSE",
  "name": "New York Stock Exchange",
  "country": "US",
  "currency": "USD",
  "timezone": "America/New_York",
  "stock_count": 2417,
  "etf_count": 389
}

Error bodies are JSON with a detail field explaining what happened.

• The API is read-only. GET requests only.
• Only active instruments and dividend events are served. Delisted symbols and discarded events never appear in any response.
• Dates are YYYY-MM-DD. Decimals come as strings to preserve precision; parse them with your language's decimal type, not float, if you care about cents.
• Regenerating your key in the dashboard invalidates the old one instantly. Do it whenever a key may have leaked.
• Don't cache and republish the dataset. The terms of service apply to API usage too.
• Building something cool with this? Tell us about it.