{ "openapi": "3.0.0", "info": { "title": "OpenFIGI 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": [] } ], "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." } } } } } } }, "/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." } } } } } } }, "/search": { "post": { "description": "Search for FIGIs using key words and other filters.", "requestBody": { "description": "Search query object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchRequest" }, "examples": { "simple": { "$ref": "#/components/examples/simpleSearchRequest" } } } } }, "responses": { "200": { "description": "A list of FIGIs and their metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "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." } } } } } } }, "/filter": { "post": { "description": "Search for FIGIs using key words and other filters. The results are listed alphabetically by FIGI and include the number of results.", "requestBody": { "description": "Filter query object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterRequest" }, "examples": { "simple": { "$ref": "#/components/examples/simpleFilterRequest" } } } } }, "responses": { "200": { "description": "A list of FIGIs and their metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FilterResponse" } } } }, "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." } } } } } } } }, "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" ] }, "NullableNumberInterval": { "maxItems": 2, "minItems": 2, "type": "array", "description": "At least one entry should be non-null.", "nullable": true, "items": { "type": "number", "nullable": true } }, "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 } }, "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" } } }, "SearchRequest": { "type": "object", "properties": { "query": { "type": "string", "example": "Apple" }, "start": { "type": "string", "description": "The number of results returned for any given request is fixed. When more results are accessible, the response will contain a next property whose value should be sent in succeeding requests as the value of the start property. This will notify the API to return the next \"page\" of results.", "example": "QW9Fc1FrSkhNREF3TVZKWVJrUTAgMQ==.dannV9BsO7PRuiC2NdA2wVaJLH3fRpeeWnu3HNM73t0=" } }, "description": "At least one property in the request object must be populated.", "allOf": [ { "$ref": "#/components/schemas/CommonSearchMappingRequest" } ] }, "FilterRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/SearchRequest" } ] }, "BulkMappingJob": { "type": "array", "items": { "$ref": "#/components/schemas/MappingJob" } }, "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 } } }, "MappingJobResultFigiNotFound": { "type": "object", "properties": { "warning": { "type": "string" } } }, "MappingJobResultFigiList": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FigiResult" } } } }, "MappingJobResult": { "oneOf": [ { "$ref": "#/components/schemas/MappingJobResultFigiList" }, { "$ref": "#/components/schemas/MappingJobResultFigiNotFound" } ] }, "BulkMappingJobResult": { "type": "array", "items": { "$ref": "#/components/schemas/MappingJobResult" } }, "SearchResponseElement": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FigiResult" } }, "error": { "type": "string", "nullable": true, "example": "query must be a non-empty string." }, "next": { "type": "string", "nullable": true, "example": "QW9JSVFhUkFkQ3hDUWtjd01EQkNPVmszVnprPSAx.zqwblbHbOpBKhinclIlmUiLeMkflobBlSuWyA1Q10Ac=" } } }, "FilterResponseElement": { "type": "object", "properties": { "total": { "type": "number", "example": 1255917 } }, "allOf": [ { "$ref": "#/components/schemas/SearchResponseElement" } ] }, "SearchResponse": { "type": "array", "items": { "$ref": "#/components/schemas/SearchResponseElement" } }, "FilterResponse": { "type": "array", "items": { "$ref": "#/components/schemas/FilterResponseElement" } }, "inline_response_200": { "type": "object", "properties": { "values": { "type": "array", "items": { "type": "string" } } } } }, "responses": { "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." } } } }, "404": { "description": "Not Found", "content": { "text/html; charset=utf-8": { "schema": { "type": "string", "example": "Invalid url." } } } }, "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." } } } }, "413": { "description": "Content Too Large", "content": { "text/html; charset=utf-8": { "schema": { "type": "string", "example": "Payload too large." } } } }, "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." } } } } }, "examples": { "simpleMappingRequest": { "summary": "Simple mapping request", "value": [ { "idType": "ID_BB_GLOBAL", "idValue": "BBG000BLNNH6" } ] }, "simpleSearchRequest": { "summary": "Simple search request", "value": { "query": "ibm", "exchCode": "US" } }, "simpleFilterRequest": { "summary": "Simple filter request", "value": { "query": "ibm", "exchCode": "US" } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "name": "X-OPENFIGI-APIKEY", "in": "header" } } } }