FinancialReports API Documentation

Welcome to the FinancialReports API documentation. This API provides programmatic access to a comprehensive database of financial filings, company information, and industry classifications primarily focused on European markets.

Base URL

All API requests should be made using the following base URL. All endpoint paths listed below are relative to this base URL.

https://api.financialreports.eu/

Authentication

All API endpoints require authentication via an API key. You must include your unique API key in the X-API-Key HTTP header with every request.

Example Header:

X-API-Key: your_api_key_here

Obtaining an API Key

Enterprise & Research Solutions: For tailored enterprise or research institution access, please contact us via our contact form: https://financialreports.eu/pricing/

Rate Limiting & Quotas

To ensure service stability and fair usage, the FinancialReports API implements a dual-layer rate limiting architecture. Every request is subject to two checks:

Burst Limit (Speed): A short-term limit (e.g., requests per second) to prevent system overload.

Monthly Quota (Volume): A long-term limit based on your subscription plan (e.g., requests per month).

Response Headers

Every authenticated API response includes headers to help you track your usage in real-time. We recommend logging these headers to monitor your consumption programmatically.

Header Name	Description
`X-RateLimit-Burst-Limit`	The maximum speed allowed by your plan (e.g., `50/second` or `5/minute`).
`X-RateLimit-Monthly-Limit`	Your total request allowance for the current billing period.
`X-RateLimit-Monthly-Remaining`	The number of requests you have left in the current billing period.

Handling Rate Limit Errors (429)

If you exceed a limit, the API returns a 429 Too Many Requests status code. The response body will clearly indicate which limit was hit so your application can handle it appropriately.

Scenario 1: Burst Limit Exceeded

Cause: You are sending requests too fast.

Action: Pause your script for a few seconds (exponential backoff) and retry.

{
  "error": "Too Many Requests",
  "detail": "Request was throttled. Expected available in 2 seconds.",
  "retry_after_seconds": 2,
  "type": "burst_limit_exceeded",
  "message": "You are sending requests too quickly.",
  "resolution": "Implement exponential backoff or reduce concurrency."
}

Scenario 2: Quota Limit Exceeded

Cause: You have used all your credits for the month.

Action: Upgrade your plan or wait until the next billing cycle.

{
  "error": "Too Many Requests",
  "detail": "Request was throttled. Expected available in 84300 seconds.",
  "retry_after_seconds": 84300,
  "type": "quota_limit_exceeded",
  "message": "You have exhausted your API request quota for the current billing period.",
  "resolution": "Upgrade your plan or wait for the next billing cycle."
}

Available Endpoints

The API provides read-only access to most resources, with specific actions for managing user watchlists.

Companies

Access detailed company information.

GET /companies/ - Retrieve a paginated list of companies. Supports extensive filtering (ISIC, location, identifiers), searching, and ordering.

GET /companies/{id}/ - Retrieve detailed information for a single company by its internal ID.

Filings

Access regulatory filing data and its processed content.

GET /filings/ - Retrieve a paginated list of filings. Supports extensive filtering (company identifiers, location, filing attributes, date ranges), searching, and ordering.

GET /filings/{id}/ - Retrieve detailed information for a single filing by its ID.

GET /filings/{id}/markdown/ - Retrieve the raw, processed Markdown content for a single filing.

ISIC Classifications

Access reference data for the International Standard Industrial Classification of All Economic Activities (ISIC).

Sections:

GET /isic-sections/ - List ISIC Sections. Supports filtering and searching.

GET /isic-sections/{id}/ - Retrieve a specific ISIC Section.

Divisions:

GET /isic-divisions/ - List ISIC Divisions. Supports filtering and searching.

GET /isic-divisions/{id}/ - Retrieve a specific ISIC Division.

Groups:

GET /isic-groups/ - List ISIC Groups. Supports filtering and searching.

GET /isic-groups/{id}/ - Retrieve a specific ISIC Group.

Classes:

GET /isic-classes/ - List ISIC Classes. Supports filtering and searching.

GET /isic-classes/{id}/ - Retrieve a specific ISIC Class.

Reference Data

Access other reference and lookup data.

Filing Types:

GET /filing-types/ - List filing types. Supports searching.

GET /filing-types/{id}/ - Retrieve a specific filing type.

Sources:

GET /sources/ - List data sources.

GET /sources/{id}/ - Retrieve a specific data source.

Languages:

GET /languages/ - List all supported languages for filings.

GET /languages/{id}/ - Retrieve a specific language.

Countries:

GET /countries/ - List all supported countries.

GET /countries/{id}/ - Retrieve a specific country.

User Watchlist

Manage your personal watchlist of companies.

GET /watchlist/ - Get the current user's watchlist of companies.

POST /watchlist/companies/ - Add a company to the user's watchlist. Requires company_id in the request body.

DELETE /watchlist/companies/{company_id}/ - Remove a company from the user's watchlist.

Common Parameters for List Endpoints

Most list endpoints support the following common query parameters for pagination, searching, and ordering:

page (Integer): The page number for pagination (default is 1).

page_size (Integer): The number of results per page (default is 20, configurable per plan or request up to a maximum).

search (String): A general search term. The specific fields searched vary by endpoint (e.g., company name, filing title, ISIC codes).

ordering (String): Field name to order results by. Prefix with - for descending order (e.g., name, -release_datetime). Supported fields vary by endpoint.

For detailed filtering parameters available on specific endpoints (e.g., /filings/, /companies/), please refer to the interactive OpenAPI documentation.

Response Format

All API responses are returned in JSON format, except for the /filings/{id}/markdown/ endpoint, which returns plain text.

Successful Responses (200 OK, 201 Created)

List Endpoints (GET): Return a paginated structure:

{
  "count": 123,
  "next": "https://api.financialreports.eu/api/endpoint/?page=3",
  "previous": "https://api.financialreports.eu/api/endpoint/?page=1",
  "results": [
    { /* object 1 data */ },
    { /* object 2 data */ }
  ] \
} \

Retrieve Endpoints (GET): Return a single JSON object representing the requested resource:

{ \
  "id": 123, \
  "field_name": "value" \
  /* ... other fields ... */ \
} \

Create/Action Endpoints (POST, DELETE success): Typically return a JSON object confirming the action's status:

{
  "status": "success",
  "message": "Action performed successfully."
}

Error Responses (4xx, 5xx)

Errors are returned with an appropriate HTTP status code and a JSON body, typically containing a detail message.

General Error Example:

{
  "detail": "Error message describing the issue."
}

Field-Specific Validation Error Example (e.g., on POST):

{
  "field_name": ["Error message for this field."]
}

Error Handling Codes

The API uses standard HTTP response codes to indicate the success or failure of a request:

200 OK: The request was successful.

201 Created: The resource was successfully created (e.g., adding a company to a watchlist).

400 Bad Request: The request was invalid or cannot be otherwise served.

401 Unauthorized: Authentication credentials (API Key) were missing, are invalid, or the key is inactive.

403 Forbidden: Authentication succeeded, but the authenticated user does not have permission to perform the requested action.

404 Not Found: The requested resource could not be found.

429 Too Many Requests: The user has sent too many requests in a given amount of time (rate limit exceeded).

500 Internal Server Error: An unexpected error occurred on our servers.

SDKs / Client Libraries

To help you integrate with our API more easily, we provide an official Python client library.

📘 Python Usage Guide: Read the full documentation
Start here for installation instructions, code examples, and best practices.

GitHub Repository: https://github.com/financial-reports/financial-reports-python

PyPI Package: https://pypi.org/project/financial-reports-generated-client/

test

Installation (Python):

pip install financial-reports-generated-client

Support

If you encounter issues, have questions, or require assistance, please contact our support team at support@financialreports.eu.

This documentation provides a high-level overview. For detailed information on specific endpoints, request/response schemas, all available filtering parameters, and interactive examples, please refer to the comprehensive OpenAPI (Swagger) documentation generated from our API schema.

FinancialReports API Documentation

Base URL#

Authentication#

Obtaining an API Key#

Rate Limiting & Quotas#

Response Headers#

Handling Rate Limit Errors (429)#

Available Endpoints#

Companies#

Filings#

ISIC Classifications#

Sections:#

Divisions:#

Groups:#

Classes:#

Reference Data#

Filing Types:#

Sources:#

Languages:#

Countries:#

User Watchlist#

Common Parameters for List Endpoints#

Response Format#

Successful Responses (200 OK, 201 Created)#

List Endpoints (GET): Return a paginated structure:#

Retrieve Endpoints (GET): Return a single JSON object representing the requested resource:#

Create/Action Endpoints (POST, DELETE success): Typically return a JSON object confirming the action's status:#

Error Responses (4xx, 5xx)#

General Error Example:#

Field-Specific Validation Error Example (e.g., on POST):#

Error Handling Codes#

SDKs / Client Libraries#

Installation (Python):#

Support#