Whether you're new to APIs or simply looking for more examples of commonly used endpoints, the following documentation will help you learn how to use the IEX Cloud API.  

This article will cover:  

  • How to build a request: A step-by-step guide for using the API 

  • Examples: See commonly used queries and sample API requests 

  • Next steps: Get started next with SSE streaming, batching, and other best practices 

How to build a request 

Our API is designed for simplicity. It uses HTTPS REST calls to request and receive back data from IEX Cloud, where every call is made up of the base URL, version, an endpoint-specific path, and a query string: 

Base URL: Use one of the two base URLs for all REST calls. When first getting started with IEX Cloud, it's best to begin with free testing by using our sandbox. Learn more about getting started with sandbox testing here.  

Version: Use “stable” for all requests. This ensures that you’re using the current version of the API.  

Endpoint path: This is the path specific to each endpoint and depends on the data you would like to access. Examples include:  

  • Balance Sheet: /stock/{symbol}/balance-sheet/{last}/{field} 

  • Quote: /stock/{symbol}/quote/{field} 

The enclosed portions { } above are path parameters. When you make an API call, you need to replace the {parameter} with values. The values you use for the parameters help determine the data you’ll get back for the call.  

Certain path parameters are required, such as {symbol} in the above examples. In other cases, they are optional — such as {field} and {last} for “Balance Sheet.” 

If a path parameter is optional, there will be a default response when it is not included. The values for path parameters and default responses can be found for each endpoint under the “Path Parameters” header in the API documentation.   

Query string parameters: Query string parameters are how you can further filter or sort the data returned from an API call. Like path parameters, certain query string parameters are required, while others are optional.  

The query string always begins with the question mark character “?” and comes last in a REST call. The query string is a series of parameters represented as “parameter=value.” IEX Cloud query strings include:  

  • Your token (required): Every call you make must include either your production or test tokens. Unless an API call specifies that it requires your secret key, you should use a publishable key for all calls. Include your token in the following format: “token=YOUR_TOKEN_HERE.” 

  • Additional query parameters: Some endpoints support additional parameters that can be passed as part of the query string. For example, the Financials endpoint has a period query string parameter that allows you to specify if you want annual or quarterly financials. The query string parameters for any endpoint will be shown under the “Query String Parameters” header. 

Parameters in a query string must be separated by the ampersand character “&.” For example, if you want to pull annual financials from the financials endpoint, your query string would be “?token=YOUR_TOKEN_HERE&period=annual.” Note that the order of parameters in a query string is irrelevant, so you could also write it as “?period=annual&token=YOUR_TOKEN_HERE.”  

The values for all parameters need to be URL-encoded. For example, if you wanted to use AIG+ as a symbol, you would need to URL-encode the "+" sign.  

More information about query string parameters can be found in our API documentation.  


Putting it all together 

Now you’re ready to build an API request. Here’s one complete example. 

Let's say you want to pull IBM's annual financials. Using the API documentation as a guide, you would structure your call like this: 

https://cloud.iexapis.com/stable/stock/IBM/financials?token=YOUR_TOKEN_HERE&period=annual

Base: https://cloud.iexapis.com/
Version: stable/
Endpoint Path: stock/{symbol}/financials/
Query String Parameters: token=YOUR_TOKEN_HERE&period={} 

See additional examples further down in this article.  



Sandbox testing 

If you're new to IEX Cloud, we suggest that you begin with sandbox testing to craft your first few API requests free of charge. While API calls made to the production environment use your plan’s credits, API calls for sandbox testing do not use your credits and are unlimited. 

Learn more about sandbox testing here.    


Examples and commonly used API requests 

Below are a couple of simple, frequently used API requests. Before using any of the following examples with the production API, check the data weight in our API documentation to see how many credits would be used per call.  

1) See current stock price details for ExxonMobil (XOM), using the Quote endpoint.  

https://cloud.iexapis.com/stable/stock/XOM/quote?token=YOUR_TOKEN_HERE 

 2) See today's intraday prices by minute for Bank of America (BAC), returning the last 20 minutes only, using the Intraday Prices endpoint.  

https://cloud.iexapis.com/stable/stock/BAC/intraday-prices?token=YOUR_TOKEN_HERE&chartLast=20  

3) See Facebook's historical intraday prices by minute for a specific date, using the Historical Prices endpoint. Historical minute bar data is currently supported for the last trailing 30-day window from today's date. 

https://cloud.iexapis.com/stable/stock/FB/chart/date/20191107?token=YOUR_TOKEN_HERE 

 You can also see additional examples by logging into the IEX Cloud Console and searching for any symbol in the upper-left-hand corner, as shown below. After clicking into a specific symbol, you will see additional examples under “Popular API Calls.”


What's next?  

Did this answer your question?