financialfilings-com Security Listings API

openapi: 3.2.0
info:
  title: FinancialFilings Security Listings API
  version: 1.4.0
  description: 'Filings and company data for listed companies across the G20 and Europe. Send your API key in the `X-API-Key` header on every request. New here? Start with the quickstart.


    **Credits.** Every call costs credits, and each endpoint below shows its price. `X-Credits-Charged` on the response says what a call cost, and `GET /usage/` shows the month so far. A free account gets a monthly allowance. Webhooks are an Enterprise feature. Pricing: https://financialfilings.com/developers/


    **Rate limits.** Responses carry `X-RateLimit-Burst-Limit` (a rate such as `50/second`), `X-RateLimit-Monthly-Limit`, `X-RateLimit-Monthly-Remaining` and `X-RateLimit-Monthly-Unit` (`requests` or `credits`). All four are strings and can be non-numeric (for example `Unlimited`); the last two are left out when they don''t apply.'
  termsOfService: https://financialfilings.com/api-terms/
  contact:
    name: API Support
    url: https://financialfilings.com/
    email: api@financialfilings.com
servers:
- url: https://api.financialreports.eu
  description: Production API Gateway
tags:
- name: Security Listings
  description: 'Exchange listings per company: venue, ticker and FIGI.'
paths:
  /security-listings/:
    get:
      operationId: security_listings_list
      description: 'Where each company''s shares trade: one row per exchange, with its ticker and FIGI. Filter by `ticker`, `mic`, `exch_code` or `figi` to find the company behind a listing, or by `company` to list its venues.'
      summary: List Security Listings
      parameters:
      - in: query
        name: company
        schema:
          type: number
        description: Company ID.
      - in: query
        name: exch_code
        schema:
          type: string
        description: OpenFIGI exchange code, e.g. `US`. Case-insensitive.
      - in: query
        name: figi
        schema:
          type: string
        description: FIGI of the listing. Case-insensitive.
      - in: query
        name: mic
        schema:
          type: string
        description: ISO 10383 market identifier code, e.g. `XNAS`. Case-insensitive.
      - name: ordering
        required: false
        in: query
        description: Which field to use when ordering the results.
        schema:
          type: string
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: ticker
        schema:
          type: string
        description: Ticker on that venue. Case-insensitive.
      tags:
      - Security Listings
      security:
      - ApiKeyAuth: []
      - CognitoJWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSecurityListingList'
          description: ''
        '403':
          description: Missing or invalid API key, or the plan does not include this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
              examples:
                MissingCredentials:
                  summary: No X-API-Key header
                  value:
                    detail: Authentication credentials were not provided.
                    type: authentication_required
                    resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
                    dashboard_url: https://financialfilings.com/accounts/api-dashboard/
                InvalidKey:
                  summary: Unknown or inactive API key
                  value:
                    detail: Invalid or inactive API key.
                PlanDoesNotPermit:
                  summary: Plan does not include this endpoint
                  value:
                    detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
        '429':
          description: Rate limit, plan quota or spend cap reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                BurstLimit:
                  summary: Too many requests per minute
                  value:
                    error: Too Many Requests
                    detail: Request was throttled. Expected available in 12 seconds.
                    retry_after_seconds: 12
                    scope: burst
                    type: burst_limit_exceeded
                    message: 'Rate limit reached: 120 requests per minute.'
                    resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
                    rate_limit: 120/minute
                    payg_url: https://financialfilings.com/accounts/payg/
  /security-listings/{id}/:
    get:
      operationId: security_listings_retrieve
      description: One exchange listing by its ID.
      summary: Retrieve Security Listing
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        description: A unique integer value identifying this security listing.
        required: true
      tags:
      - Security Listings
      security:
      - ApiKeyAuth: []
      - CognitoJWT: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SecurityListing'
          description: ''
        '403':
          description: Missing or invalid API key, or the plan does not include this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDetail'
              examples:
                MissingCredentials:
                  summary: No X-API-Key header
                  value:
                    detail: Authentication credentials were not provided.
                    type: authentication_required
                    resolution: 'Send your API key in the X-API-Key request header, e.g. curl -H "X-API-Key: <your key>" https://api.financialreports.eu/filings/ . A browser address bar never sends this header. No key yet? Get a free one at https://financialfilings.com/accounts/api-dashboard/ .'
                    dashboard_url: https://financialfilings.com/accounts/api-dashboard/
                InvalidKey:
                  summary: Unknown or inactive API key
                  value:
                    detail: Invalid or inactive API key.
                PlanDoesNotPermit:
                  summary: Plan does not include this endpoint
                  value:
                    detail: Your current plan does not permit access. Requires a plan that includes **structured financials**.
        '429':
          description: Rate limit, plan quota or spend cap reached.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
              examples:
                BurstLimit:
                  summary: Too many requests per minute
                  value:
                    error: Too Many Requests
                    detail: Request was throttled. Expected available in 12 seconds.
                    retry_after_seconds: 12
                    scope: burst
                    type: burst_limit_exceeded
                    message: 'Rate limit reached: 120 requests per minute.'
                    resolution: 'Retry after 12 seconds (Retry-After header). Pay-as-you-go raises this to 50/sec: https://financialfilings.com/accounts/payg/'
                    rate_limit: 120/minute
                    payg_url: https://financialfilings.com/accounts/payg/
components:
  schemas:
    PaginatedSecurityListingList:
      type: object
      required:
      - count
      - results
      properties:
        count:
          type: integer
          example: 123
          description: 'Total matching results. Exact for cheap queries, an estimate on broad or expensive ones. Do not use it to decide when to stop: follow `next` until it is null.'
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        results:
          type: array
          items:
            $ref: '#/components/schemas/SecurityListing'
    CompanyMinimal:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
          description: Unique identifier for the company.
        name:
          type: string
          readOnly: true
          description: Company name.
        tagline:
          type: string
          readOnly: true
          description: A short, one-liner describing the company's value proposition.
        isins:
          type: array
          items:
            type: string
          readOnly: true
          description: Primary ISIN(s) for the company. Use the company detail endpoint for the full list.
        lei:
          type: string
          readOnly: true
          description: Legal Entity Identifier (ISO 17442).
        sub_industry_code:
          type:
          - string
          - 'null'
          readOnly: true
          description: ISIC classification code classifying the company.
        oics_code:
          type:
          - string
          - 'null'
          readOnly: true
          description: The company's primary OICS class code (public preview, OICS v0.3), e.g. `TC.SC.SEM.CHP`. Null when the company has no class under the current OICS version, including entity types that carry none (funds, shells, financing vehicles). The full label is the `oics` object on the full company representation.
        country_code:
          type: string
          readOnly: true
          description: ISO 3166-1 alpha-2 country code of the company's primary registration or headquarters.
        date_public:
          type:
          - string
          - 'null'
          format: date
          readOnly: true
          description: 'Date this company record was last updated on the FinancialFilings platform. This is not the IPO or listing date: that is `date_ipo` on `GET /companies/{id}/`. With `id`, it is the `date_public_cursor` of an incremental company sync.'
      required:
      - country_code
      - date_public
      - id
      - isins
      - lei
      - name
      - oics_code
      - sub_industry_code
      - tagline
    RateLimitError:
      type: object
      description: Body of a 429 response. The `Retry-After` header carries the same wait as `retry_after_seconds`. Only `detail` is always present.
      properties:
        detail:
          type: string
          description: A human-readable message describing the error.
        error:
          type: string
          description: Always `Too Many Requests`.
        retry_after_seconds:
          type:
          - integer
          - 'null'
          description: Seconds until the request may be retried, when known.
        scope:
          type:
          - string
          - 'null'
          description: Which limit was hit, e.g. `burst`, `quota` or `payg_velocity`.
        type:
          type: string
          description: Machine-readable error code, e.g. `burst_limit_exceeded`, `quota_limit_exceeded`, `daily_spend_cap_reached` or `monthly_spend_ceiling_reached`.
        message:
          type: string
          description: A human-readable explanation of the limit.
        resolution:
          type: string
          description: A human-readable hint on what to do next.
        upgrade_url:
          type: string
          description: 'Where to upgrade: the pay-as-you-go card page for free accounts, else the plans page (quota errors).'
        limit:
          type: integer
          description: The plan allowance that was used up (quota errors).
        interval:
          type: string
          description: '`monthly` or `annual` (quota errors).'
        resets_on:
          type: string
          format: date
          description: UTC date the allowance resets (quota errors).
        rate_limit:
          type: string
          description: The per-minute limit that refused the request, e.g. `120/minute` (burst errors).
        payg_url:
          type: string
          description: Where to enable pay-as-you-go (quota and burst errors, when it applies).
        dashboard_url:
          type: string
          description: Where to see current spend (spend-cap and spend-ceiling errors).
        contact_url:
          type: string
          description: Where to ask for a higher limit (spend-cap and spend-ceiling errors).
      required:
      - detail
    ErrorDetail:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable message describing the error.
        type:
          type: string
          description: Machine-readable error code, e.g. `authentication_required`. Present on some errors only.
        resolution:
          type: string
          description: A human-readable hint on how to fix the request. Present on some errors only.
        error_type:
          type: string
          description: Machine-readable error code on validation errors. Present on some errors only.
      required:
      - detail
    SecurityListing:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        company:
          allOf:
          - $ref: '#/components/schemas/CompanyMinimal'
          readOnly: true
        mic:
          type: string
          readOnly: true
        ticker:
          type: string
          readOnly: true
        exch_code:
          type: string
          readOnly: true
        exchange_name:
          type:
          - string
          - 'null'
          readOnly: true
          description: Display name of the exchange, when the MIC maps to a known venue.
        security_type:
          type: string
          readOnly: true
        market_sector:
          type: string
          readOnly: true
        figi:
          type: string
          readOnly: true
        composite_figi:
          type: string
          readOnly: true
        share_class_figi:
          type: string
          readOnly: true
      required:
      - company
      - composite_figi
      - exch_code
      - exchange_name
      - figi
      - id
      - market_sector
      - mic
      - security_type
      - share_class_figi
      - ticker
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: 'Server-to-server API key authentication. Provide your key in the `X-API-Key` request header. Keys can be generated and rotated from your account dashboard: https://financialfilings.com/profile/'
    CognitoJWT:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'AWS Cognito-issued JWT access token. Provide the token in the `Authorization` header as: `Authorization: Bearer <access_token>`. Tokens are issued via the Cognito hosted UI or the OAuth2 authorization code flow at `https://auth.financialreports.eu`.'