openapi: 3.2.0
info:
  description: The future of fintech.
  title: Polygon Reference:sec:filings API
  version: 1.0.0
servers:
- description: Polygon Platform API
  url: https://api.polygon.io
- description: Polygon Platform API (Staging)
  url: https://api.staging.polygon.io
security:
- apiKey: []
tags:
- name: reference:sec:filings
paths:
  /v1/reference/sec/filings:
    x-polygon-draft: true
    get:
      description: List filings
      operationId: ListFilings
      parameters:
      - description: Query by filing type.
        in: query
        name: type
        schema:
          description: Filing Type
          enum:
          - 10-K
          - 10-Q
          type: string
      - description: Query by filing date.
        in: query
        name: filing_date
        schema:
          description: The date when the filing was filed in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
        x-polygon-filter-field:
          range: true
      - description: Query by period of report.
        in: query
        name: period_of_report_date
        schema:
          description: The period of report for the filing in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
        x-polygon-filter-field:
          range: true
      - description: 'If true, query only for filings with an XBRL instance file.

          If false, query for filings without an XBRL instance file.

          If this parameter is not provided, query for filings with or without XBRL instance files.'
        in: query
        name: has_xbrl
        schema:
          type:
          - boolean
          - 'null'
        x-polygon-go-id: HasXBRL
      - description: Query by entity company name.
        in: query
        name: entities.company_data.name
        schema:
          example: Facebook Inc
          type: string
        x-polygon-filter-field:
          search: true
      - description: Query by entity company CIK.
        in: query
        name: entities.company_data.cik
        schema:
          description: Central Index Key (CIK) Number
          type: string
      - description: Query by entity company ticker.
        in: query
        name: entities.company_data.ticker
        schema:
          description: Ticker
          type: string
      - description: Query by entity company SIC.
        in: query
        name: entities.company_data.sic
        schema:
          description: Standard Industrial Classification (SIC)
          type: string
      - description: Search by filing_date.
        in: query
        name: filing_date.gte
        schema:
          description: The date when the filing was filed in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by filing_date.
        in: query
        name: filing_date.gt
        schema:
          description: The date when the filing was filed in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by filing_date.
        in: query
        name: filing_date.lte
        schema:
          description: The date when the filing was filed in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by filing_date.
        in: query
        name: filing_date.lt
        schema:
          description: The date when the filing was filed in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by period_of_report_date.
        in: query
        name: period_of_report_date.gte
        schema:
          description: The period of report for the filing in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by period_of_report_date.
        in: query
        name: period_of_report_date.gt
        schema:
          description: The period of report for the filing in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by period_of_report_date.
        in: query
        name: period_of_report_date.lte
        schema:
          description: The period of report for the filing in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by period_of_report_date.
        in: query
        name: period_of_report_date.lt
        schema:
          description: The period of report for the filing in YYYYMMDD format.
          example: '20210101'
          pattern: ^[0-9]{8}$
          type: string
      - description: Search by entities.company_data.name.
        in: query
        name: entities.company_data.name.search
        schema:
          type: string
      - description: Order results based on the `sort` field.
        in: query
        name: order
        schema:
          enum:
          - asc
          - desc
          example: asc
          type: string
      - description: Limit the number of results returned, default is 10 and max is 1000.
        in: query
        name: limit
        schema:
          default: 10
          example: 10
          maximum: 1000
          minimum: 1
          type: integer
      - description: Sort field used for ordering.
        in: query
        name: sort
        schema:
          default: filing_date
          enum:
          - filing_date
          - period_of_report_date
          example: filing_date
          type: string
      responses:
        '200':
          content:
            application/json:
              description: FIXME
              example: {}
              schema:
                properties:
                  count:
                    type: integer
                  next_url:
                    type: string
                  request_id:
                    type: string
                  results:
                    items:
                      properties:
                        acceptance_datetime:
                          description: 'The datetime when the filing was accepted by EDGAR in EST (format: YYYYMMDDHHMMSS)'
                          type: string
                        accession_number:
                          description: Filing Accession Number
                          type: string
                        entities:
                          description: Entities related to the filing (e.g. the document filers).
                          items:
                            description: A filing entity (e.g. the document filer).
                            properties:
                              company_data:
                                properties:
                                  cik:
                                    description: Central Index Key (CIK) Number
                                    type: string
                                  name:
                                    example: Facebook Inc
                                    type: string
                                  sic:
                                    description: Standard Industrial Classification (SIC)
                                    type: string
                                  ticker:
                                    description: Ticker
                                    type: string
                                required:
                                - name
                                - cik
                                - sic
                                type: object
                                x-polygon-go-type:
                                  name: SECCompanyData
                                  path: github.com/polygon-io/go-lib-models/v2/globals
                              relation:
                                description: Relationship of this entity to the filing.
                                enum:
                                - filer
                                type: string
                            required:
                            - relation
                            type: object
                            x-polygon-go-type:
                              name: SECFilingEntity
                              path: github.com/polygon-io/go-lib-models/v2/globals
                          type: array
                        files_count:
                          description: The number of files associated with the filing.
                          format: int64
                          type: integer
                        filing_date:
                          description: The date when the filing was filed in YYYYMMDD format.
                          example: '20210101'
                          pattern: ^[0-9]{8}$
                          type: string
                        id:
                          description: Unique identifier for the filing.
                          type: string
                        period_of_report_date:
                          description: The period of report for the filing in YYYYMMDD format.
                          example: '20210101'
                          pattern: ^[0-9]{8}$
                          type: string
                        source_url:
                          description: 'The source URL is a link back to the upstream source for this filing

                            document.'
                          example: https://www.sec.gov/Archives/edgar/data/0001326801/000132680119000037/0001326801-19-000037-index.html
                          format: uri
                          type: string
                        type:
                          description: Filing Type
                          enum:
                          - 10-K
                          - 10-Q
                          type: string
                      required:
                      - id
                      - accession_number
                      - type
                      - filing_date
                      - period_of_report_date
                      - files_count
                      - source_url
                      - download_url
                      - entities
                      type: object
                      x-polygon-go-type:
                        name: SECFiling
                        path: github.com/polygon-io/go-lib-models/v2/globals
                    type: array
                  status:
                    type: string
                required:
                - status
                - request_id
                - count
                - results
                type: object
          description: FIXME
      summary: SEC Filings
      tags:
      - reference:sec:filings
      x-polygon-entitlement-data-type:
        description: Reference data
        name: reference
      x-polygon-paginate:
        sort:
          default: filing_date
          enum:
          - filing_date
          - period_of_report_date
components:
  securitySchemes:
    apiKey:
      in: query
      name: apiKey
      type: apiKey
x-polygon-order:
  crypto:
    market:
    - launchpad: shared
      paths:
      - /v2/aggs/ticker/{cryptoTicker}/range/{multiplier}/{timespan}/{from}/{to}
    - launchpad: exclusive
      paths:
      - /v1/summaries
    - paths:
      - /v2/aggs/grouped/locale/global/market/crypto/{date}
    - paths:
      - /v1/open-close/crypto/{from}/{to}/{date}
    - paths:
      - /v2/aggs/ticker/{cryptoTicker}/prev
    - paths:
      - /v3/trades/{cryptoTicker}
    - paths:
      - /v1/historic/crypto/{from}/{to}/{date}
    - paths:
      - /v1/last/crypto/{from}/{to}
    - group: Snapshots
      paths:
      - /v2/snapshot/locale/global/markets/crypto/tickers
      - /v2/snapshot/locale/global/markets/crypto/{direction}
      - /v2/snapshot/locale/global/markets/crypto/tickers/{ticker}
      - /v2/snapshot/locale/global/markets/crypto/tickers/{ticker}/book
      - /v3/snapshot
    - group: Technical Indicators
      paths:
      - /v1/indicators/sma/{cryptoTicker}
      - /v1/indicators/ema/{cryptoTicker}
      - /v1/indicators/macd/{cryptoTicker}
      - /v1/indicators/rsi/{cryptoTicker}
    reference:
    - paths:
      - /v3/reference/tickers
    - paths:
      - /v1/marketstatus/upcoming
    - paths:
      - /v1/marketstatus/now
    - paths:
      - /v3/reference/conditions
    - paths:
      - /v3/reference/exchanges
  fx:
    market:
    - launchpad: shared
      paths:
      - /v2/aggs/ticker/{forexTicker}/range/{multiplier}/{timespan}/{from}/{to}
    - launchpad: exclusive
      paths:
      - /v1/summaries
    - paths:
      - /v2/aggs/grouped/locale/global/market/fx/{date}
    - paths:
      - /v2/aggs/ticker/{forexTicker}/prev
    - paths:
      - /v3/quotes/{fxTicker}
    - paths:
      - /v1/historic/forex/{from}/{to}/{date}
    - paths:
      - /v1/last_quote/currencies/{from}/{to}
    - paths:
      - /v1/conversion/{from}/{to}
    - group: Snapshots
      paths:
      - /v2/snapshot/locale/global/markets/forex/tickers
      - /v2/snapshot/locale/global/markets/forex/{direction}
      - /v2/snapshot/locale/global/markets/forex/tickers/{ticker}
      - /v3/snapshot
    - group: Technical Indicators
      paths:
      - /v1/indicators/sma/{fxTicker}
      - /v1/indicators/ema/{fxTicker}
      - /v1/indicators/macd/{fxTicker}
      - /v1/indicators/rsi/{fxTicker}
    reference:
    - paths:
      - /v3/reference/tickers
    - paths:
      - /v1/marketstatus/upcoming
    - paths:
      - /v1/marketstatus/now
    - paths:
      - /v3/reference/conditions
    - paths:
      - /v3/reference/exchanges
  indices:
    market:
    - launchpad: shared
      paths:
      - /v2/aggs/ticker/{indicesTicker}/range/{multiplier}/{timespan}/{from}/{to}
    - paths:
      - /v2/aggs/ticker/{indicesTicker}/prev
    - paths:
      - /v1/open-close/{indicesTicker}/{date}
    - group: Technical Indicators
      paths:
      - /v1/indicators/sma/{indicesTicker}
      - /v1/indicators/ema/{indicesTicker}
      - /v1/indicators/macd/{indicesTicker}
      - /v1/indicators/rsi/{indicesTicker}
    - group: Snapshots
      paths:
      - /v3/snapshot/indices
      - /v3/snapshot
    reference:
    - paths:
      - /v3/reference/tickers
    - paths:
      - /v3/reference/tickers/types
    - paths:
      - /v1/marketstatus/upcoming
    - paths:
      - /v1/marketstatus/now
  options:
    market:
    - launchpad: shared
      paths:
      - /v2/aggs/ticker/{optionsTicker}/range/{multiplier}/{timespan}/{from}/{to}
    - launchpad: exclusive
      paths:
      - /v1/summaries
    - paths:
      - /v1/open-close/{optionsTicker}/{date}
    - paths:
      - /v2/aggs/ticker/{optionsTicker}/prev
    - paths:
      - /v3/trades/{optionsTicker}
    - paths:
      - /v2/last/trade/{optionsTicker}
    - paths:
      - /v3/quotes/{optionsTicker}
    - group: Snapshots
      paths:
      - /v3/snapshot/options/{underlyingAsset}/{optionContract}
      - /v3/snapshot/options/{underlyingAsset}
      - /v3/snapshot
    - group: Technical Indicators
      paths:
      - /v1/indicators/sma/{optionsTicker}
      - /v1/indicators/ema/{optionsTicker}
      - /v1/indicators/macd/{optionsTicker}
      - /v1/indicators/rsi/{optionsTicker}
    reference:
    - paths:
      - /v3/reference/options/contracts/{options_ticker}
    - paths:
      - /v3/reference/options/contracts
    - paths:
      - /v3/reference/tickers
    - paths:
      - /v1/meta/symbols/{stocksTicker}/company
    - paths:
      - /v3/reference/tickers/{ticker}
    - paths:
      - /v2/reference/news
    - paths:
      - /v3/reference/tickers/types
    - paths:
      - /v1/marketstatus/upcoming
    - paths:
      - /v1/marketstatus/now
    - paths:
      - /v3/reference/conditions
    - paths:
      - /v3/reference/exchanges
  stocks:
    market:
    - launchpad: shared
      paths:
      - /v2/aggs/ticker/{stocksTicker}/range/{multiplier}/{timespan}/{from}/{to}
    - launchpad: exclusive
      paths:
      - /v1/summaries
    - paths:
      - /v2/aggs/grouped/locale/us/market/stocks/{date}
    - paths:
      - /v1/open-close/{stocksTicker}/{date}
    - paths:
      - /v2/aggs/ticker/{stocksTicker}/prev
    - paths:
      - /v3/trades/{stockTicker}
    - paths:
      - /v2/ticks/stocks/trades/{ticker}/{date}
    - paths:
      - /v2/last/trade/{stocksTicker}
    - paths:
      - /v3/quotes/{stockTicker}
    - paths:
      - /v2/ticks/stocks/nbbo/{ticker}/{date}
    - paths:
      - /v2/last/nbbo/{stocksTicker}
    - group: Snapshots
      paths:
      - /v2/snapshot/locale/us/markets/stocks/tickers
      - /v2/snapshot/locale/us/markets/stocks/{direction}
      - /v2/snapshot/locale/us/markets/stocks/tickers/{stocksTicker}
      - /v3/snapshot
    - group: Technical Indicators
      paths:
      - /v1/indicators/sma/{stockTicker}
      - /v1/indicators/ema/{stockTicker}
      - /v1/indicators/macd/{stockTicker}
      - /v1/indicators/rsi/{stockTicker}
    reference:
    - paths:
      - /v3/reference/tickers
    - paths:
      - /v1/meta/symbols/{stocksTicker}/company
    - paths:
      - /v3/reference/tickers/{ticker}
    - paths:
      - /vX/reference/tickers/{id}/events
    - paths:
      - /v2/reference/news
    - paths:
      - /v3/reference/tickers/types
    - paths:
      - /vX/reference/tickers/taxonomies
    - paths:
      - /v1/marketstatus/upcoming
    - paths:
      - /v1/marketstatus/now
    - group: SEC Filings
      paths:
      - /v1/reference/sec/filings
      - /v1/reference/sec/filings/{filing_id}
      - /v1/reference/sec/filings/{filing_id}/files
      - /v1/reference/sec/filings/{filing_id}/files/{file_id}
    - paths:
      - /v3/reference/splits
    - paths:
      - /v3/reference/dividends
    - paths:
      - /vX/reference/financials
    - paths:
      - /v3/reference/conditions
    - paths:
      - /v3/reference/exchanges
    - paths:
      - /v1/related-companies/{ticker}
    - paths:
      - /vX/reference/ipos
    - paths:
      - /vX/reference/short-interest/{identifier_type}/{identifier}
    - paths:
      - stocks/vX/listings
      - stocks/vX/listing/{identifier_type}/{identifier}
      - stocks/vX/listings/updates