openapi: 3.0.3
info:
title: OpenFIGI API
description: |
The OpenFIGI API is the free, public REST API operated by Bloomberg as
Registration Authority for the Object Management Group (OMG) Financial
Instrument Global Identifier (FIGI) standard. It maps third-party
identifiers (TICKER, ID_ISIN, ID_CUSIP, ID_SEDOL, ID_BB_GLOBAL, COMPOSITE_ID_BB_GLOBAL,
etc.) to FIGIs and exposes search and filter endpoints across hundreds of
millions of active and inactive securities.
The /v3 API is JSON over HTTPS. Authentication is optional via the
`X-OPENFIGI-APIKEY` header; supplying an API key raises rate limits.
Note: /v2 is deprecated with a sunset date of July 1, 2026 — clients should
migrate to /v3 endpoints and switch error handling from "error" to "warning"
on no-match responses.
version: '3.0.0'
contact:
name: OpenFIGI Support
url: https://www.openfigi.com/api
license:
name: OpenFIGI Terms of Service
url: https://www.openfigi.com/about/terms
servers:
- url: https://api.openfigi.com/v3
description: OpenFIGI v3 production
tags:
- name: Mapping
description: Map third-party identifiers to FIGIs.
- name: Search
description: Keyword search across the FIGI universe.
- name: Filter
description: Filtered, paginated search across the FIGI universe.
- name: Reference
description: Enumerated values for request and response fields.
security:
- {}
- ApiKeyAuth: []
paths:
/mapping:
post:
operationId: mapIdentifiers
summary: Map Third-Party Identifiers To FIGIs
description: |
Map one or more third-party identifiers (ticker, ISIN, CUSIP, SEDOL,
Bloomberg Global ID, etc.) to FIGI records. The request body is a JSON
array of mapping jobs. Each job is processed independently and returns
either matched data, a warning (no match), or an error.
Without an API key: 25 requests/minute, up to 10 jobs per request.
With an API key: 25 requests/6 seconds, up to 100 jobs per request.
tags:
- Mapping
requestBody:
required: true
content:
application/json:
schema:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/MappingJob'
examples:
ticker_lookup:
summary: TICKER lookup for IBM US
value:
- idType: TICKER
idValue: IBM
exchCode: US
responses:
'200':
description: Per-job mapping results, in the same order as the request.
headers:
X-RateLimit-Limit:
schema:
type: integer
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/MappingJobResult'
examples:
ibm_us_match:
summary: TICKER=IBM, exchCode=US match
value:
- data:
- figi: BBG000BLNNH6
name: INTL BUSINESS MACHINES CORP
ticker: IBM
exchCode: US
compositeFIGI: BBG000BLNNH6
securityType: Common Stock
marketSector: Equity
shareClassFIGI: BBG001S5S399
securityType2: Common Stock
securityDescription: IBM
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
'503':
$ref: '#/components/responses/ServiceUnavailable'
/mapping/values/{key}:
get:
operationId: listMappingValues
summary: List Enumerated Values For A Mapping Field
description: |
Return the list of valid values for an enum-like mapping field such as
`idType`, `exchCode`, `currency`, `securityType`, `securityType2`,
`marketSecDes`, `micCode`, or `stateCode`.
tags:
- Reference
parameters:
- name: key
in: path
required: true
description: The mapping field to enumerate.
schema:
type: string
enum:
- idType
- exchCode
- currency
- micCode
- marketSecDes
- securityType
- securityType2
- stateCode
responses:
'200':
description: Valid values for the given field.
content:
application/json:
schema:
type: object
properties:
values:
type: array
items:
type: string
'400':
$ref: '#/components/responses/BadRequest'
'404':
$ref: '#/components/responses/NotFound'
/search:
post:
operationId: searchFigis
summary: Keyword-Search The FIGI Universe
description: |
Search across the FIGI universe by free-text query plus optional
filters such as exchCode, currency, securityType, marketSecDes, and
date ranges. Results are paginated with the opaque `start` cursor
returned in the previous response.
Without an API key: 5 requests/minute. With an API key: 20 requests/minute.
Results are capped at 15,000 records per query.
tags:
- Search
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Search results.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/ServerError'
/filter:
post:
operationId: filterFigis
summary: Filter The FIGI Universe With Result Counts
description: |
Filter the FIGI universe with optional keyword query, returning results
sorted alphabetically by FIGI plus a `total` count of matches. Useful
for inventorying a population of securities matching a set of criteria.
Without an API key: 5 requests/minute. With an API key: 20 requests/minute.
Results are capped at 15,000 records per query.
tags:
- Filter
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SearchRequest'
responses:
'200':
description: Filter results with total count.
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/SearchResponse'
- type: object
properties:
total:
type: integer
description: Total matching records.
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-OPENFIGI-APIKEY
description: |
Optional OpenFIGI API key. Sign up at https://www.openfigi.com/user/signup
to receive a key and unlock higher rate limits.
schemas:
MappingJob:
type: object
required:
- idType
- idValue
properties:
idType:
type: string
description: The third-party identifier type.
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
- BASE_TICKER
- ID_CUSIP_8_CHR
- OCC_SYMBOL
- UNIQUE_ID_FUT_OPT
- OPRA_SYMBOL
- TRADING_SYSTEM_IDENTIFIER
- ID_CINS
- ID_BB_PROP
- VENDOR_INDEX_CODE
idValue:
type: string
description: The identifier value.
exchCode:
type: string
description: Exchange code filter (e.g. US, LN, GR).
micCode:
type: string
description: ISO 10383 Market Identifier Code filter.
currency:
type: string
description: ISO 4217 currency code filter (e.g. USD, EUR).
marketSecDes:
type: string
description: Bloomberg market sector description (e.g. Equity, Comdty, Govt, Corp, Index, Curncy).
securityType:
type: string
description: Security type filter (e.g. Common Stock, Future, Option).
securityType2:
type: string
description: Secondary security type filter.
includeUnlistedEquities:
type: boolean
description: Whether to include unlisted equities in results.
optionType:
type: string
enum: [Call, Put]
strike:
type: array
items:
type: number
nullable: true
minItems: 2
maxItems: 2
description: Strike range as [min, max]; either bound may be null.
contractSize:
type: array
items:
type: number
nullable: true
minItems: 2
maxItems: 2
coupon:
type: array
items:
type: number
nullable: true
minItems: 2
maxItems: 2
expiration:
type: array
items:
type: string
nullable: true
format: date
minItems: 2
maxItems: 2
maturity:
type: array
items:
type: string
nullable: true
format: date
minItems: 2
maxItems: 2
stateCode:
type: string
MappingJobResult:
type: object
description: |
Each result has exactly one of `data`, `warning`, or `error`.
properties:
data:
type: array
items:
$ref: '#/components/schemas/FigiRecord'
warning:
type: string
description: Non-fatal condition such as "No identifier found."
error:
type: string
description: Fatal error processing this job.
FigiRecord:
type: object
properties:
figi:
type: string
description: The 12-character Financial Instrument Global Identifier.
example: BBG000BLNNH6
name:
type: string
description: Long name of the instrument.
ticker:
type: string
exchCode:
type: string
compositeFIGI:
type: string
description: Composite (country-level) FIGI for this instrument.
uniqueID:
type: string
securityType:
type: string
marketSector:
type: string
description: Bloomberg market sector (Equity, Comdty, Govt, Corp, Index, Curncy, Pfd, Muni, M-Mkt).
shareClassFIGI:
type: string
description: Share-class FIGI grouping multiple composite FIGIs for the same share class.
uniqueIDFutOpt:
type: string
nullable: true
securityType2:
type: string
securityDescription:
type: string
metadata:
type: string
nullable: true
SearchRequest:
type: object
required:
- query
properties:
query:
type: string
description: Free-text query string.
exchCode:
type: string
micCode:
type: string
currency:
type: string
marketSecDes:
type: string
securityType:
type: string
securityType2:
type: string
includeUnlistedEquities:
type: boolean
start:
type: string
description: Opaque pagination cursor from a previous response.
SearchResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/FigiRecord'
next:
type: string
description: Opaque cursor for the next page; absent on the final page.
responses:
BadRequest:
description: Malformed request (validation failed, schema mismatch, etc.).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
Unauthorized:
description: Invalid X-OPENFIGI-APIKEY.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
NotFound:
description: Resource not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
TooManyRequests:
description: Rate limit exceeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
ServerError:
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
ServiceUnavailable:
description: Service temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorBody'
examples: {}