Data model and field conventions

Our identifiers

Use report_id in API calls, and report_id or report_key as your primary key. The year in report_key is the cover year, which can differ from the fiscal year. Use content_sha256 to detect a changed PDF.

Querying with your identifiers

Resolution is exact; we do not guess. Each call takes up to 1,000 identifiers across all lists, and returns one result per input, in input order. A company we hold outside your licence comes back as matched: true, entitled: false with no details. An identifier that maps to more than one company comes back as matched: false, ambiguous: true, so a conflict is never resolved silently.

{"isins": ["IT0000062072", "XX0000000000"]}

{
  "results": [
    {"query": "IT0000062072", "identifier_type": "isin", "matched": true, "entitled": true,
     "company": {"company_key": "XMIL_G", "company_name": "Assicurazioni Generali SpA", "isin": "IT0000062072",
                 "lei": "549300X5UKJVE386ZB61", "figi": "BBG001S68DX0", "cik": null, "fiscal_year_end_month": 12,
                 "ticker": "G", "mic": "XMIL", "exchange": "Borsa Italiana (Euronext Milan)", "country": "Italy",
                 "sector": "Finance & insurance", "industry": "Insurance & pensions"}},
    {"query": "XX0000000000", "identifier_type": "isin", "matched": false, "entitled": null,
     "company": null}
  ],
  "matched_count": 1,
  "unmatched_count": 1
}

For a large list, we can also prepare a crosswalk file during onboarding: one row per company on your list, with your identifier, our company_key and the match status. If you believe a match is wrong, email us the company_key and your identifier and we will correct it.

Identifiers we return

We return ISIN, LEI, FIGI and CIK where we hold them, plus our own keys and the listing: ticker, MIC and exchange.

Report types

report_type is one of these codes. SR, IR, AR2 and AR1 are the core types; the four-letter codes are specialty disclosures. We may add codes: treat an unknown code as a valid specialty disclosure.

An AR2 is an annual report with a dedicated, substantive sustainability section. An AR1 is an annual report without one. report_class groups documents more broadly: D for a standalone sustainability report, E for sustainability disclosure inside a larger report, S for a specialised ESG document and F for an annual report without substantive sustainability content.

The Report object

Every report endpoint returns the same Report object. It carries typed API fields, grouped below, and a metadata object with the same information under the 50 field-guide column names.

Fields outside the 50 are API-only: report_id, has_file, download_path, formats, created_at, updated_at, report_hash, document_scope, report_fcyear, report_period, report_pubdate (date form), report_edition (string form of edition_number) and report_assurance (same value as assurance_provider).

Field conventions

• Unknown is null. A value we do not have is null in the typed fields and an empty string in metadata.
• A blank is never a no. For the boolean fields, false (FALSE in metadata) means we found evidence the report does not apply the standard or feature. null (empty in metadata) means undetermined.
• Extracted, not audited. Standards flags and assurance fields describe what the report states. They are not an independent audit.
• Two forms of the same data. The typed API fields use integers, booleans, dates and null. The metadata object always carries all 50 columns, every value a string, exactly as in a bulk delivery file: dates in ISO 8601, booleans as TRUE, FALSE or empty. Use whichever suits you.
• Times and sizes. created_at and updated_at are UTC. report_filesize is in megabytes. report_pubdate_iso keeps the precision the report states: YYYY, YYYY-MM or YYYY-MM-DD.
• Languages. report_lang holds ISO 639-1 codes; a bilingual report carries two. The language filter matches either.

Fiscal year

report_fcyear is the fiscal year a report covers. When a company's fiscal year spans two calendar years, the report is tagged with the year in which that fiscal year ends. An Indian annual report for April 2024 to March 2025, labelled 2024-25 by the company, is fiscal year 2025.

• The company's own label stays in fiscal_year_label, for example 2024-2025. The exact dates are in period_start_date and period_end_date.
• The fcyear filter and the fiscal-year window of your licence use the same convention.
• When a report states no fiscal year, its cover year (report_year) is used instead.
• Undated documents have cover year 0 and no fiscal year. They fall outside any fiscal-year window.
• The cover year can differ from the fiscal year: a report printed in 2024 can cover fiscal year 2025, and its report_key then contains 2024.

The 50 metadata fields

Every report carries the 50 fields of the metadata field guide (schema version V3). The table shows the column name used in metadata and in bulk deliveries, and the matching typed API field. GET /meta/schema returns the same dictionary in machine-readable form.

Company changes

Mergers, renames and re-listings happen. When a company's key changes we tell you, and the change feed reports the affected reports as updates. See staying current for how to apply them.