DEVELOPERS · API V1

Documents, with their source attached.

Read stored issuer IR documents from EarningsDeck. Coverage is issuer-specific; a company page does not mean its full IR archive has been collected.

Read-only endpointsJSON + original filesPartial coverage is identified

Make your first request

Company documents are returned in pages.

Access

These read endpoints currently require no API key. Set EARNINGSDECK_BASE_URL to the host you use. No public rate-limit guarantee is published; keep polling conservative. Responses include stored records only and never trigger a collection.

cURL

BASE_URL="${EARNINGSDECK_BASE_URL:-http://localhost:3100}"
curl --get "$BASE_URL/api/v1/companies/NYSE%3AWFC/documents" \
  --data-urlencode "limit=20" \
  --data-urlencode "offset=0" \
  --data-urlencode "q=quarterly results"

JavaScript

const baseUrl = process.env.EARNINGSDECK_BASE_URL ?? "http://localhost:3100";
const url = new URL("/api/v1/companies/NYSE%3AWFC/documents", baseUrl);
url.searchParams.set("limit", "20");
url.searchParams.set("q", "quarterly results");

const response = await fetch(url);
if (!response.ok) throw new Error("EarningsDeck API: " + response.status);
const result = await response.json();
console.log(result.documents, result.coverage);

Use an exchange-qualified ticker in the company path, such as NYSE%3AWFC or JSE%3ASBK. URL-encode the colon between exchange and ticker.

Endpoints

Published and stored records only.

GET/api/v1/companies/{exchange%3Aticker}/documents

List and search stored issuer IR documents.

Available for pilot companies. Query with q, category, year, sort, limit and offset. q searches document metadata and stored extracted text. category accepts Results report, Presentation, Transcript, Prepared remarks, Dividend announcement, Factsheet, Invitation, Other report, Results announcement or Financial supplement. year matches reportingYear. limit defaults to 20 (1–100); offset defaults to 0. sort accepts title or oldest; the default is newest reporting year first. The response includes total, nextOffset, partial-coverage metadata and on-domain document, text and download URLs.

GET/api/v1/documents/{id}

Read metadata for a document returned in a list response.

Returns the public record and whether the original file is stored. Unknown ids return 404.

GET/api/v1/documents/{id}/text

Retrieve extracted document text.

Returns text/plain UTF-8 for search and downstream processing. Text can be unavailable when no extracted asset was stored.

GET/api/v1/documents/{id}/download

Retrieve a stored original PDF.

Add inline=1 for inline display. Supports HTTP byte ranges. This endpoint serves files already stored by EarningsDeck; it does not fetch from the issuer on demand.

Coverage and errors

Read coverage fields before relying on a result.

Partial by design

Issuer document responses identify selected sources and covered years. A company page is not proof of a complete IR archive.

Stored files only

Document routes serve stored issuer originals; they do not fetch from the issuer on demand.

Bounded queries

Document listing limit defaults to 20 and accepts 1–100. Offset must be non-negative; q is limited to 300 characters.

Common responses

400 invalid query · 404 company or document is unknown or unpublished · 503 stored data is temporarily unavailable. A document listing response can still return HTTP 200 with zero matching records.

Following companies and email alerts are authenticated product workflows, not part of this public read API. Availability depends on the deployed storage configuration and published coverage.

Back to companies