Bitvore Financial Filings API

openapi: 3.2.0
info:
  description: '## Precision News API


    The Precision News APIs provide access to curated news annotated with metadata tags.'
  version: '1.0'
  title: Bitvore Legacy Financial Filings API
  license:
    name: Copyright Bitvore Corp. 2026
servers:
- url: https://api.bitvore.com/
tags:
- name: Financial Filings
  description: Financial Filings API
paths:
  /financialfiling/submissions:
    get:
      tags:
      - Financial Filings
      summary: Financial Filings Submissions Query
      description: 'Returns full submissions for the financial filings that meet the supplied criteria. Financial filings can be selected with the following options:

        * Filing Type - Type of filing, i.e., 8-K, 10-Q, etc.

        * Bitvore ID - A Bitvore ID, known as a BvId, uniquely identifies a company/organization. Querying by BvId returns only filings submitted by that company.

        * Free Form Text Search - A search for words or phrases can be performed against the filings matching any of the previous options listed.

        * Include Summary - If set to true a summary file will be included with each submission with the fields described in the Get Summary operation. If false no summary file will be included.

        * Org Field - By default the subject company of a filing is identified by its ID and its name. Additional fields will be returned for each company if specified here. The available options are name, domainName, ticker, city, state, and country. If available the additional fields will be returned in the Org object in the summary. Note: Returning additional fields may cause a small increase in latency. This option is only applicable if summaries are included.


        This API operation is a file download operation. This call will download a compressed file holding the individual files from the original submission. Based on the Accept header provided by the client, the download file will either be a gzipped tar file (application/x-gzip) or a zip file (application/zip and the default).


        The following are some examples of using the API.


        To query for the filings submitted by IBM, BvId b00001ab7 within the last 30 days in the PST timezone using gzip compression (using query param for api key):


        ```js

        GET /financialfiling/submissions?bvId=b00001ab7&offset=30&tz=PST&key=xyz123 HTTP 1.1

        Accept: application/x-gzip

        ```


        To query for all the 10-Q filings submitted within the last 30 days in the PST timezone and return summary information:


        ```js

        GET /financialfiling/submissions?filingType=10-Q&includeSummary=true&offset=30&tz=PST&key=xyz123 HTTP 1.1

        Accept: application/gzip

        ```


        The file that is downloaded as a result of this call when decompressed (and extracted for the tar.gz option) will create a directory structure where each submission will get its own directory named with the key of the submission. All of the files that are part of the submission and the optional summary file will be placed in its directory. For example:


        ```

        040000016b8b62e290bcb7e16fcb95b79000ad663679cbdb8566671c

        summary.json

        june2019slb8-k.htm

        ex991june2019slb.htm

        bxclogoa43.jpg

        1301787/000130178719000056/0001301787-19-000056.txt

        050000016b8b61adf8ad07fe0fd21063bd517de42f81fbfc5166671c

        summary.json

        eh1900853_8k.htm

        eh1900853_ex0201.htm

        eh1900853_ex1001.htm

        0000950142-19-001409.txt

        ```'
      operationId: downloadFilingsUsingGET
      parameters:
      - name: filingType
        in: query
        description: Types of filings to return
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: bvId
        in: query
        description: Organizations of filings to return
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: includeSummary
        in: query
        description: Value of true will return a summary file with the filing files
        required: false
        allowEmptyValue: false
        schema:
          type: boolean
      - name: text
        in: query
        description: Keyword or phrase to search for in the filings.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: orgField
        in: query
        description: One or more fields to return for each organization associated with the returned articles, by default only the organization's Id and name is returned. Available options are name, domainName, ticker, city, state, country
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: startDate
        in: query
        description: Filing date to start from. Format is yyyy-mm-dd for daily filings or yyyy-mm-dd'T'HH:mm if you want it down to the hour or minute. Should not be used if offset parameter is.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: endDate
        in: query
        description: Filing date to end with. Format is yyyy-mm-dd for daily (inclusive) filings or yyyy-mm-dd'T'HH:mm if you want it down to the hour or minute. If startDate is used and endDate is not the default endDate is today.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: offset
        in: query
        description: Number of days back filings should be returned for. Should not be used with startDate. Default is 31.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
      - name: tz
        in: query
        description: Timezone used in startDate and endDate.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: GMT
      - name: dateType
        in: query
        description: Indicates whether dates to query by should be submission dates "submitted" or available dates (processing completed) "available". Default is submitted.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: submitted
      - name: pageNo
        in: query
        description: Page number of the total result set to return, default is 1.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        description: Number of results out of the total result set per page to return, default is 100, maximum is 200.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 100
      responses:
        '200':
          description: Success
          content:
            application/x-gzip:
              schema:
                $ref: '#/components/schemas/InputStreamResource'
                originalRef: InputStreamResource
            application/zip:
              schema:
                $ref: '#/components/schemas/InputStreamResource'
                originalRef: InputStreamResource
        '401':
          description: Unauthorized to view filings
          content:
            application/x-gzip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
            application/zip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
        '500':
          description: Internal error
          content:
            application/x-gzip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
            application/zip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
      security:
      - API key:
        - Global
      - BasicAuth:
        - Global
      - OAuth:
        - Global
      deprecated: false
  /financialfiling/submissions/{filingId}:
    get:
      tags:
      - Financial Filings
      summary: Financial Filing Submission
      description: 'Returns the submission with the given key. The key is a unique identifier that can be found in the response to the Get Summaries call. This call will download a compressed file holding the individual files from the original submission. Based on the Accept header provided by the client, the download file will either be a gzipped tar file (application/x-gzip) or a zip file (application/zip and the default).


        An example of downloading a gzipped submission is


        ```js

        GET /financialfiling/submissions/060000016b9045f018c6e719ba884ef6605ccf6503a4733cf377651c HTTP 1.1

        Accept: application/x-gzip

        ```


        A sample successful response will be a gzipped tar file of the files from the original submission. If the submission was made to the SEC html files (with accompanying images) as well as a master text file will be included.'
      operationId: downloadFilingUsingGET
      parameters:
      - name: filingId
        in: path
        description: Bitore Id of the filing
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/x-gzip:
              schema:
                $ref: '#/components/schemas/InputStreamResource'
                originalRef: InputStreamResource
            application/zip:
              schema:
                $ref: '#/components/schemas/InputStreamResource'
                originalRef: InputStreamResource
        '401':
          description: Unauthorized to view filing
          content:
            application/x-gzip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
            application/zip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
        '500':
          description: Internal error
          content:
            application/x-gzip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
            application/zip:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
      security:
      - API key:
        - Global
      - BasicAuth:
        - Global
      - OAuth:
        - Global
      deprecated: false
  /financialfiling/summaries:
    get:
      tags:
      - Financial Filings
      summary: Financial Filing Summaries Query
      description: ${legacy.download.summaries.notes}
      operationId: getFilingsUsingGET
      parameters:
      - name: filingType
        in: query
        description: Types of filings to return
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: bvId
        in: query
        description: Organizations of filings to return
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: text
        in: query
        description: Keyword or phrase to search for in the filings.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: startDate
        in: query
        description: Filing date to start from. Format is yyyy-mm-dd for daily filings or yyyy-mm-dd'T'HH:mm if you want it down to the hour or minute. Should not be used if offset parameter is.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: endDate
        in: query
        description: Filing date to end with. Format is yyyy-mm-dd for daily (inclusive) filings or yyyy-mm-dd'T'HH:mm if you want it down to the hour or minute. If startDate is used and endDate is not the default endDate is today.
        required: false
        allowEmptyValue: false
        schema:
          type: string
      - name: offset
        in: query
        description: Number of days back filings should be returned for. Should not be used with startDate. Default is 31.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
      - name: tz
        in: query
        description: Timezone used in startDate and endDate.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: GMT
      - name: dateType
        in: query
        description: Indicates whether dates to query by should be submission dates "submitted" or available dates (processing completed) "available". Default is submitted.
        required: false
        allowEmptyValue: false
        schema:
          type: string
          default: submitted
      - name: orgField
        in: query
        description: One or more fields to return for each organization associated with the returned articles, by default only the organization's Id and name is returned. Available options are name, domainName, ticker, city, state, country
        required: false
        allowEmptyValue: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: pageNo
        in: query
        description: Page number of the total result set to return, default is 1.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 1
      - name: pageSize
        in: query
        description: Number of results out of the total result set per page to return, default is 100, maximum is 1000.
        required: false
        allowEmptyValue: false
        schema:
          type: integer
          format: int32
          default: 100
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FinancialFilingsSearchResponseLegacy'
                originalRef: FinancialFilingsSearchResponseLegacy
        '401':
          description: Unauthorized to view filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReasonResponse'
                originalRef: ReasonResponse
      security:
      - API key:
        - Global
      - BasicAuth:
        - Global
      - OAuth:
        - Global
      deprecated: false
components:
  schemas:
    InputStreamResource:
      type: object
      properties:
        description:
          type: string
        file:
          $ref: '#/components/schemas/File'
          originalRef: File
        filename:
          type: string
        inputStream:
          $ref: '#/components/schemas/InputStream'
          originalRef: InputStream
        open:
          type: boolean
        readable:
          type: boolean
        uri:
          $ref: '#/components/schemas/URI'
          originalRef: URI
        url:
          $ref: '#/components/schemas/URL'
          originalRef: URL
      title: InputStreamResource
    FinancialFilingLegacy:
      type: object
      properties:
        availableAt:
          type: string
          example: '2017-06-29T21:41:21.109Z'
          description: Date submitted
        filingId:
          type: string
          description: Id of the filing unique to the filing source, the Id format may be different per source.
        filingType:
          type: string
          example: 10-K
          description: Type of the filing, i.e., 10-K, 8-Q
        key:
          type: string
          example: 070000015cf083aba01f0826ecfe718e965b577c572166b14a77651c
          description: Key uniquely identifying the filing in Bitvore
        org:
          description: Organization the filing is about.
          $ref: '#/components/schemas/OrganizationReference'
          originalRef: OrganizationReference
        publishedAt:
          type: string
          example: '2017-06-29T21:41:21.109Z'
          description: Date available
        sourceUrl:
          type: string
          example: http://acme.com/press
          description: URL to the original source of the filing
        text:
          type: string
          description: Text of the primary section of the filing. Filings are initially in HTML, all markup is removed and remaining text is returned. No exhibits or addendums are included.
        title:
          type: string
          description: Title of the filing
      title: FinancialFilingLegacy
      description: An entity's financial filing.
    OrganizationReference:
      type: object
      properties:
        bvId:
          type: string
          example: b00001ab7
          description: Bitvore Id of the organization
        city:
          type: string
          example: IRVINE
          description: City the organization is headquartered in.
        country:
          type: string
          example: UNITED STATES
          description: Country the organization is headquartered in.
        domainName:
          type: string
          example: acme.com
          description: Domain name of the organization.
        factsetId:
          type: string
          example: 000DWY-E
          description: 'FactSet ID of the organization. (Requires License: ''FACTSET_ID'')'
        isin:
          type: string
          example: US5949181045
          description: 'ISIN of the organization. (Requires License: ''ISIN'')'
        name:
          type: string
          example: ACME Corp
          description: Name of the organization.
        state:
          type: string
          example: CA
          description: State (code) the organization is headquartered in.
        ticker:
          type: string
          example: ACME
          description: Primary ticker of the organization (if public).
      title: OrganizationReference
      description: Reference to an organization
    FinancialFilingsSearchResponseLegacy:
      type: object
      required:
      - returned
      - total
      properties:
        reason:
          type: string
          example: Could not locate subject.
          description: Text reason for the failure (if not successful)
        reasonSupport:
          type: string
          example: Longer description of the missing subject.
          description: Additional information about the failure (if not successful)
        response:
          type: array
          description: Response payload
          items:
            $ref: '#/components/schemas/FinancialFilingLegacy'
            originalRef: FinancialFilingLegacy
        returned:
          type: integer
          format: int32
          example: 10
          description: Number of filings returned by search, maximum amount dictated by the pageSize parameter used in search
        success:
          type: boolean
          example: true
          description: Indicates whether the call was successful or not
        total:
          type: integer
          format: int32
          example: 100
          description: Total number of financial filings found by search
      title: FinancialFilingsSearchResponseLegacy
      description: Financial filings search response.
    URL:
      type: object
      properties:
        authority:
          type: string
        content:
          type: object
        defaultPort:
          type: integer
          format: int32
        file:
          type: string
        host:
          type: string
        path:
          type: string
        port:
          type: integer
          format: int32
        protocol:
          type: string
        query:
          type: string
        ref:
          type: string
        userInfo:
          type: string
      title: URL
    InputStream:
      type: object
      title: InputStream
    File:
      type: object
      properties:
        absolute:
          type: boolean
        absoluteFile:
          $ref: '#/components/schemas/File'
          originalRef: File
        absolutePath:
          type: string
        canonicalFile:
          $ref: '#/components/schemas/File'
          originalRef: File
        canonicalPath:
          type: string
        directory:
          type: boolean
        file:
          type: boolean
        freeSpace:
          type: integer
          format: int64
        hidden:
          type: boolean
        name:
          type: string
        parent:
          type: string
        parentFile:
          $ref: '#/components/schemas/File'
          originalRef: File
        path:
          type: string
        totalSpace:
          type: integer
          format: int64
        usableSpace:
          type: integer
          format: int64
      title: File
    URI:
      type: object
      properties:
        absolute:
          type: boolean
        authority:
          type: string
        fragment:
          type: string
        host:
          type: string
        opaque:
          type: boolean
        path:
          type: string
        port:
          type: integer
          format: int32
        query:
          type: string
        rawAuthority:
          type: string
        rawFragment:
          type: string
        rawPath:
          type: string
        rawQuery:
          type: string
        rawSchemeSpecificPart:
          type: string
        rawUserInfo:
          type: string
        scheme:
          type: string
        schemeSpecificPart:
          type: string
        userInfo:
          type: string
      title: URI
    ReasonResponse:
      type: object
      properties:
        reason:
          type: string
          example: Could not locate subject.
          description: Text reason for the failure (if not successful)
        reasonSupport:
          type: object
          example: Longer description of the missing subject.
          description: Additional information about the failure (if not successful)
        response:
          type: object
          description: Response payload
        success:
          type: boolean
          example: true
          description: Indicates whether the call was successful or not
      title: ReasonResponse
      description: A response used to explain a failure or issue with the request.
  securitySchemes:
    API_key:
      type: apiKey
      name: X-BV-APIKEY
      in: header
    BasicAuth:
      type: http
      scheme: basic
    OAuth:
      type: oauth2
      flows:
        clientCredentials:
          scopes:
            Global: Includes all Bitvore APIs
          tokenUrl: https://api.bitvore.com/oauth/accesstoken