openapi: 3.0.0
info:
  title: OpenFIGI Filter Mapping API
  description: A free & open API for FIGI discovery.
  termsOfService: https://openfigi.com/docs/terms-of-service
  contact:
    name: OpenFIGI API Support
    url: https://www.openfigi.com/feedback
    email: support@openfigi.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 2.0.0
servers:
- url: https://api.openfigi.com/{basePath}
  description: Production Tier
  variables:
    basePath:
      default: v3
      enum:
      - v3
      - v2
security:
- {}
- ApiKeyAuth: []
tags:
- name: Mapping
paths:
  /mapping:
    post:
      description: Allows mapping from third-party identifiers to FIGIs.
      requestBody:
        description: A list of third-party identifiers and extra filters.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkMappingJob'
            examples:
              simple:
                $ref: '#/components/examples/simpleMappingRequest'
      responses:
        '200':
          description: A list of FIGIs and their metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkMappingJobResult'
        '400':
          description: Invalid request (body).
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              examples:
                generic:
                  value: Bad request.
                invalid_enum:
                  value: Invalid enum field.
        '401':
          description: Unauthorized.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Invalid API key.
        '405':
          description: Method Not Allowed.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Invalid HTTP method.
        '406':
          description: Not Acceptable.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Unsupported 'Accept' type.
        '415':
          description: Unsupported Media Type.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Invalid Content-Type. Should be text/json or application/json with valid charset.
        '429':
          description: Too Many Requests.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Rate limit reached. Please back off your requests.
        '500':
          description: Internal Server Error.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Internal server error.
        '503':
          description: Service Unavailable.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Service Unavailable.
      tags:
      - Mapping
  /mapping/values/{key}:
    get:
      description: Get values for enum-like fields.
      parameters:
      - name: key
        in: path
        description: Key of MappingJob for which to get possible values.
        required: true
        style: simple
        explode: false
        schema:
          type: string
          example: idType
          enum:
          - idType
          - exchCode
          - micCode
          - currency
          - marketSecDes
          - securityType
          - securityType2
      responses:
        '200':
          description: The list of values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/inline_response_200'
              examples:
                idType:
                  value:
                  - ID_BB
                  - ID_CINS
                  - ID_CUSIP
                marketSecDes:
                  value:
                  - Comdty
                  - Corp
                  - Curncy
                currency:
                  value:
                  - USD
                  - GBP
                  - EUR
                  - JPY
        '400':
          description: Invalid request (body).
          content:
            text/html; charset=utf-8:
              schema:
                type: string
              examples:
                generic:
                  value: Bad request.
                invalid_enum:
                  value: Invalid enum field.
        '401':
          description: Unauthorized.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Invalid API key.
        '405':
          description: Method Not Allowed.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Invalid HTTP method.
        '406':
          description: Not Acceptable.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Unsupported 'Accept' type.
        '415':
          description: Unsupported Media Type.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Invalid Content-Type. Should be text/json or application/json with valid charset.
        '429':
          description: Too Many Requests.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Rate limit reached. Please back off your requests.
        '500':
          description: Internal Server Error.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Internal server error.
        '503':
          description: Service Unavailable.
          content:
            text/html; charset=utf-8:
              schema:
                type: string
                example: Service Unavailable.
      tags:
      - Mapping
components:
  schemas:
    StateCode:
      type: string
      nullable: true
      enum:
      - AB
      - AC
      - AH
      - AK
      - AL
      - AM
      - AR
      - AS
      - AT
      - AZ
      - BC
      - BJ
      - CA
      - CB
      - CO
      - CQ
      - CT
      - CZ
      - DC
      - DE
      - EH
      - FH
      - FI
      - FJ
      - FL
      - FO
      - FS
      - GA
      - GD
      - GF
      - GM
      - GS
      - GU
      - GX
      - GZ
      - HA
      - HB
      - HE
      - HG
      - HI
      - HL
      - HN
      - HO
      - HS
      - IA
      - ID
      - IG
      - IK
      - IL
      - IN
      - IT
      - JL
      - JS
      - JX
      - KA
      - KC
      - KN
      - KO
      - KS
      - KT
      - KU
      - KY
      - LA
      - LN
      - MA
      - MB
      - MD
      - ME
      - MG
      - MI
      - MN
      - MO
      - MS
      - MT
      - MZ
      - NB
      - NC
      - ND
      - NE
      - NG
      - NH
      - NJ
      - NL
      - NM
      - NN
      - NR
      - NS
      - NT
      - NU
      - NV
      - NW
      - NX
      - NY
      - OH
      - OK
      - 'ON'
      - OR
      - OS
      - OT
      - OY
      - PA
      - PE
      - PR
      - QC
      - QH
      - QL
      - RI
      - SA
      - SC
      - SD
      - SH
      - SI
      - SK
      - SN
      - ST
      - SX
      - SZ
      - TA
      - TG
      - TJ
      - TK
      - TN
      - TS
      - TT
      - TX
      - TY
      - UT
      - VA
      - VI
      - VT
      - WA
      - WI
      - WK
      - WV
      - WY
      - XJ
      - XZ
      - YA
      - YN
      - YT
      - YU
      - ZJ
    inline_response_200:
      type: object
      properties:
        values:
          type: array
          items:
            type: string
    MappingJobResultFigiList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FigiResult'
    FigiResult:
      type: object
      properties:
        figi:
          type: string
          example: BBG000B9XVV8
        securityType:
          type: string
          nullable: true
          example: Common Stock
        marketSector:
          type: string
          nullable: true
          example: Equity
        ticker:
          type: string
          nullable: true
          example: AAPL
        name:
          type: string
          nullable: true
          example: APPLE INC
        exchCode:
          type: string
          nullable: true
          example: UN
        shareClassFIGI:
          type: string
          nullable: true
          example: BBG001S5N8V8
        compositeFIGI:
          type: string
          nullable: true
          example: BBG000B9XRY4
        securityType2:
          type: string
          nullable: true
          example: Common Stock
        securityDescription:
          type: string
          nullable: true
          example: AAPL
        metadata:
          type: string
          description: Exists when API is unable to show non-FIGI fields.
          nullable: true
    MappingJob:
      required:
      - idType
      - idValue
      type: object
      properties:
        idType:
          type: string
          enum:
          - ID_ISIN
          - ID_BB_UNIQUE
          - ID_SEDOL
          - ID_COMMON
          - ID_WERTPAPIER
          - ID_CUSIP
          - ID_BB
          - ID_ITALY
          - ID_EXCH_SYMBOL
          - ID_FULL_EXCHANGE_SYMBOL
          - COMPOSITE_ID_BB_GLOBAL
          - ID_BB_GLOBAL_SHARE_CLASS_LEVEL
          - ID_BB_SEC_NUM_DES
          - ID_BB_GLOBAL
          - TICKER
          - ID_CUSIP_8_CHR
          - OCC_SYMBOL
          - UNIQUE_ID_FUT_OPT
          - OPRA_SYMBOL
          - TRADING_SYSTEM_IDENTIFIER
          - ID_CINS
          - ID_SHORT_CODE
          - BASE_TICKER
          - VENDOR_INDEX_CODE
        idValue:
          oneOf:
          - type: string
          - type: integer
      description: 'For V3: securityType2 is required when idType is BASE_TICKER or ID_EXCH_SYMBOL.  expiration is required when securityType2 is Option or Warrant.  maturity is required when securityType2 is Pool.'
      allOf:
      - $ref: '#/components/schemas/CommonSearchMappingRequest'
    CommonSearchMappingRequest:
      type: object
      properties:
        exchCode:
          type: string
          nullable: true
          example: US
        micCode:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        marketSecDes:
          type: string
          nullable: true
        securityType:
          type: string
          nullable: true
          example: Equity Option
        securityType2:
          type: string
          nullable: true
          example: Option
        includeUnlistedEquities:
          type: boolean
          nullable: true
        optionType:
          type: string
          nullable: true
          enum:
          - Put
          - Call
        strike:
          $ref: '#/components/schemas/NullableNumberInterval'
        contractSize:
          $ref: '#/components/schemas/NullableNumberInterval'
        coupon:
          $ref: '#/components/schemas/NullableNumberInterval'
        expiration:
          $ref: '#/components/schemas/NullableDateInterval'
        maturity:
          $ref: '#/components/schemas/NullableDateInterval'
        stateCode:
          $ref: '#/components/schemas/StateCode'
    BulkMappingJob:
      type: array
      items:
        $ref: '#/components/schemas/MappingJob'
    MappingJobResultFigiNotFound:
      type: object
      properties:
        warning:
          type: string
    NullableNumberInterval:
      maxItems: 2
      minItems: 2
      type: array
      description: At least one entry should be non-null.
      nullable: true
      items:
        type: number
        nullable: true
    BulkMappingJobResult:
      type: array
      items:
        $ref: '#/components/schemas/MappingJobResult'
    MappingJobResult:
      oneOf:
      - $ref: '#/components/schemas/MappingJobResultFigiList'
      - $ref: '#/components/schemas/MappingJobResultFigiNotFound'
    NullableDateInterval:
      maxItems: 2
      minItems: 2
      type: array
      description: At least one entry should be non-null.
      nullable: true
      items:
        type: string
        format: date
        nullable: true
  examples:
    simpleMappingRequest:
      summary: Simple mapping request
      value:
      - idType: ID_BB_GLOBAL
        idValue: BBG000BLNNH6
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-OPENFIGI-APIKEY
      in: header