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/api/

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 and Quotas

API usage is subject to rate limits and quotas based on your subscription plan. Exceeding these limits will result in 429 Too Many Requests errors. Please consult your plan details or contact support for information specific to your account.

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 automatically generated client libraries (SDKs).

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

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

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 and Quotas#

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#