OpenFIGI Getting Started: API Key, First Request (2026)

Getting started overview

Getting started with OpenFIGI involves a few key steps: account creation, API key retrieval, and sending your first API request. The OpenFIGI API is designed to map various financial identifiers to a Financial Instrument Global Identifier (FIGI) and its associated market data, such as ticker, exchange code, and security type. The process typically uses POST requests with a JSON payload containing the identifiers you wish to map. Responses are also provided in JSON format, detailing the mapped FIGIs and their attributes. Understanding the structure of these requests and responses is fundamental to integrating OpenFIGI into your applications.

The OpenFIGI service provides a Getting Started tutorial that walks through the initial setup. This guide focuses on the practical steps to make a successful API call.

Here’s a quick overview of the process:

1. Register for an account: Obtain your unique API key.
2. Construct a request payload: Define the financial instruments you want to query using their existing identifiers.
3. Send the request: Use an HTTP client to send a POST request with your API key in the header.
4. Process the response: Parse the JSON response to extract the FIGI and related data.

Getting Started Quick Reference

Create an account and get keys

To begin using OpenFIGI, you need to register for a free account and obtain an API key. This key is essential for authenticating your requests and ensuring you adhere to the service's rate limits, especially for the free tier. OpenFIGI is free to use for both non-commercial and commercial purposes, subject to specific rate limits.

1. Navigate to the OpenFIGI API Key page: Visit the official OpenFIGI API Key registration page. You will need to provide an email address.

2. Register for an API key: Follow the prompts to register. This typically involves entering your email address. OpenFIGI will then send an email containing your unique API key.

3. Retrieve your API key: Check your inbox for an email from OpenFIGI. The email will contain a string of characters, which is your API key. Keep this key secure, as it grants access to your allocated API usage.

4. Understand API key usage: Your API key must be included in the X-OPENFIGI-APIKEY HTTP header for every request you send to the OpenFIGI API. Failure to include a valid key will result in an authentication error.

Your first request

Once you have your API key, you can make your first request to the OpenFIGI API. The primary endpoint for identifier mapping is https://api.openfigi.com/v3/mapping. All requests must be POST requests with a JSON body.

Request structure

A basic request payload is an array of job objects. Each job object specifies the identifier type (e.g., ID_TYPE) and the identifier value (e.g., ID_VALUE) for the financial instrument you want to map. Optionally, you can include a currency and marketSector to narrow down the search and improve accuracy.

Example JSON Request Body:

[
  {
    "idType": "TICKER",
    "idValue": "IBM",
    "exchCode": "US"
  },
  {
    "idType": "ISIN",
    "idValue": "US0378331005"
  }
]

Sending the request with cURL

The following cURL command demonstrates how to send a request. Replace YOUR_API_KEY with the actual key you received via email.

curl -X POST 'https://api.openfigi.com/v3/mapping' \
  -H 'Content-Type: application/json' \
  -H 'X-OPENFIGI-APIKEY: YOUR_API_KEY' \
  -d '[
    {
      "idType": "TICKER",
      "idValue": "IBM",
      "exchCode": "US"
    }
  ]'

Expected response structure

Upon a successful request, the API will return a JSON array, where each element corresponds to a job object in your request. Each response object contains a data array, which holds potential matches for the given identifier. If a match is found, it will include the FIGI, ticker, exchange code, security type, and other relevant information.

Example JSON Response:

[
  {
    "data": [
      {
        "figi": "BBG000B9XRY4",
        "name": "INTERNATIONAL BUSINESS MACHINES CORP",
        "ticker": "IBM",
        "exchCode": "US",
        "compositeFIGI": "BBG000B9XRY4",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "shareClassFIGI": "BBG001S5X449",
        "securityDescription": "IBM",
        "securityType2": "Common Stock",
        "securityId": "US4592001014",
        "securityIdType": "ISIN",
        "isin": "US4592001014"
      }
    ]
  }
]

Common next steps

After successfully making your first request, consider these common next steps to further integrate OpenFIGI into your workflow:

• Explore additional identifier types: OpenFIGI supports a wide range of input identifier types beyond Ticker and ISIN, such as CUSIP, SEDOL, WKN, and more. Refer to the OpenFIGI API documentation for a complete list and examples of how to use them to refine your queries.

• Implement in a programming language: While cURL is useful for testing, you'll likely want to integrate the API into an application using a programming language. OpenFIGI provides examples for Python, Java, and C#, demonstrating how to construct requests and parse responses programmatically. For example, Python's requests library is a common choice for making HTTP calls. For more general guidance on making HTTP requests, the Mozilla Developer Network's HTTP POST documentation offers a comprehensive overview.

• Handle rate limits: For the free tier, OpenFIGI imposes rate limits. Implement logic in your application to handle 429 Too Many Requests responses, perhaps by introducing delays or queuing requests. For higher volume needs, consider contacting OpenFIGI for commercial options.

• Error handling: Implement robust error handling for various HTTP status codes (e.g., 400 Bad Request, 401 Unauthorized) to make your integration resilient. The OpenFIGI API typically provides descriptive error messages in the JSON response body.

• Optimize queries: For bulk processing, send multiple jobs in a single request (up to 100 jobs per request). This reduces the number of API calls and improves efficiency within rate limits.

• Explore response fields: The API returns a rich set of data. Familiarize yourself with all available response fields to extract the most value, such as securityType, marketSector, and currency.

Troubleshooting the first call

Encountering issues with your first API call is common. Here are some troubleshooting tips for OpenFIGI:

• 401 Unauthorized: Invalid API Key

  • Check your API key: Ensure the API key in your X-OPENFIGI-APIKEY header exactly matches the key you received via email. Copy-pasting errors are common.
  • Verify header name: The header name must be X-OPENFIGI-APIKEY (case-sensitive).

• 400 Bad Request: Invalid JSON Payload

  • Validate JSON syntax: Use a JSON linter or validator to ensure your request body is well-formed JSON. Common errors include missing commas, unclosed brackets, or incorrect quotation marks.
  • Check required fields: Each job object in the array must contain at least idType and idValue.
  • Correct idType values: Ensure idType uses one of the supported identifier types (e.g., TICKER, ISIN, CUSIP).
  • Verify exchCode (if used): If you include exchCode, ensure it's a valid exchange code recognized by OpenFIGI, such as US for the United States.

• 429 Too Many Requests: Rate Limit Exceeded

  • Pace your requests: If you're making many requests quickly, you might hit the rate limit for the free tier. Wait a short period and try again.
  • Bundle requests: Send multiple jobs (up to 100) in a single API call instead of individual calls for each identifier.
  • Contact OpenFIGI: If you consistently hit rate limits and require higher volume, consider contacting OpenFIGI for commercial access.

• No data or empty data array in response:

  • Check identifier accuracy: Double-check that the idValue you provided is correct and corresponds to a known financial instrument.
  • Refine search with exchCode or currency: For common tickers, specifying an exchCode (e.g., US for IBM) or currency can help OpenFIGI find the correct match and reduce ambiguity.
  • Review idType and idValue combination: Ensure the idType is appropriate for the idValue (e.g., don't use ISIN for a simple ticker symbol that isn't an ISIN).

• Network or connectivity issues:

  • Verify endpoint URL: Ensure you are sending requests to https://api.openfigi.com/v3/mapping.
  • Check internet connection: Confirm your system has active internet access.
  • Firewall/Proxy settings: If you are in a corporate network, ensure your firewall or proxy settings allow outbound connections to the OpenFIGI API endpoint.