FinancialReports
    FinancialReports
    • FinancialReports API Documentation
    • Companies
      • List Companies
        GET
      • Retrieve Company Details
        GET
    • Filings
      • List Filings
        GET
      • Retrieve Filing Details
        GET
    • Processed Filings
      • Retrieve Processed Filing Content
        GET
    • Filing Types
      • List Filing Types
        GET
      • Retrieve Filing Type
        GET
    • GICS Classifications
      • List GICS Sectors
        GET
      • List GICS Industry Groups
        GET
      • List GICS Industries
        GET
      • List GICS Sub-Industries
        GET
      • Retrieve GICS Sector
        GET
      • Retrieve GICS Industry Group
        GET
      • Retrieve GICS Industry
        GET
      • Retrieve GICS Sub-Industry
        GET
    • Sources
      • List Data Sources
        GET
      • Retrieve Data Source
        GET
    • Watchlist
      • Get User's Watchlist
        GET
      • Add Company to Watchlist
        POST
      • Remove Company from Watchlist
        DELETE
    • schema
      • schema_retrieve
        GET

    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.
    Modified at 2025-05-24 07:45:48
    Next
    List Companies
    Built with