FinancialReports API Documentation

Welcome to the Financial Reports 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

There are two ways to get an API key:

Standard Plans: Choose and purchase a plan that includes API access from our pricing page: https://financialreports.eu/accounts/pricing/

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

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 (GICS, location, identifiers), searching, and ordering.

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

Filings

Access regulatory filing data.

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.

Processed Filings

Access processed content of filings.

GET /processed-filings/{id}/ - Retrieve the processed content (typically Markdown) for a single filing by its ProcessedFiling ID.

GICS Classifications

Access reference data for Global Industry Classification Standard (GICS) categories.

Sectors:

GET /sectors/ - List GICS Sectors. Supports filtering and searching.

GET /sectors/{id}/ - Retrieve a specific GICS Sector.

Industry Groups:

GET /industry-groups/ - List GICS Industry Groups. Supports filtering and searching.

GET /industry-groups/{id}/ - Retrieve a specific GICS Industry Group.

Industries:

GET /industries/ - List GICS Industries. Supports filtering and searching.

GET /industries/{id}/ - Retrieve a specific GICS Industry.

Sub-Industries:

GET /sub-industries/ - List GICS Sub-Industries. Supports filtering and searching.

GET /sub-industries/{id}/ - Retrieve a specific GICS Sub-Industry.

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.

User Watchlist

Manage your personal watchlist of companies.

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

POST /watchlist/ (or /watchlist/add/ depending on your URL configuration) - Add a company to the user's watchlist. Requires company_id in the request body.

DELETE /watchlist/{company_id}/ (or /watchlist/remove/{company_id}/ depending on your URL configuration) - Remove a company from the user's watchlist using the company ID from the URL path.

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, GICS 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.

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, often with a relevant ID:

{
  "status": "success",
  "message": "Action performed successfully.",
  "company_id": 456
  /* ... other relevant fields ... */
}

Error Responses (4xx, 5xx)

Errors are returned with an appropriate HTTP status code and a JSON body, typically containing a detail message. Specific error structures may vary for validation errors versus general errors.

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. This may be due to invalid parameters, malformed JSON, or a violation of business rules (e.g., trying to add a company already in a watchlist). The response body will often contain details about the specific error(s).

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 or access the requested resource. This can be due to plan limitations or other authorization constraints.

404 Not Found: The requested resource (e.g., a specific company ID or filing ID) 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):

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#

Processed Filings#

GICS Classifications#

Sectors:#

Industry Groups:#

Industries:#

Sub-Industries:#

Reference Data#

Filing Types:#

Sources:#

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, often with a relevant ID:#

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#