To get started with FINRA's API Platform first familiarize yourself with the content published here on the API Developer Center. FINRA's API platform is a sophisticated REST based solution with advanced querying capabilities. Becoming familiar with its features will help you build a proper connection to the platform.

Once familiar with the features of the platform, the next step will be to complete any preliminary steps that your organization may need to complete in order to onboard to the API Platform and get access to the API Console hosted on FINRA Gateway.

The API Console provides self-service API Credential provisioning and management features for API Developers. 


Please contact the API team with any questions on getting started.

Terms of Service

Info for the Firm SAA

The Super Account Administrator (SAA) for your firm is responsible for managing the accounts at your organization that require access to the FINRA API Console.

The API Console is a FINRA Gateway hosted app that allows appropriate individuals in your firm, authorized by the SAA or a designated Account Administrator (AA), to provision API Credentials for use with the FINRA API platform.

Provisioned API Credentials will be displayed in the Account Administration App in FINRA Gateway (labeled as Machine to Machine) and will be part of the annual FINRA entitlement account certification process, but can only be managed (create, update, delete) via the API Console.

The first step in providing authorized users with access to the FINRA API Console is to request that the FINRA Entitlement Team assign the API Console Entitlement to the SAA's FINRA Entitlement Admin Account. This step is required because as an extra level of security, FINRA has not automatically assigned the API Console Entitlement to SAA Admin Accounts.

To request access to this entitlement  the firm SAA must complete and submit an API Console Entitlement Request.This request will be processed by the FINRA Entitlement Team within 3 business days and the SAA will receive an email indicating that the API Console entitlement has been assigned to the SAA's Admin account. Please note that the API Console entitlement is assigned to the SAA's Admin account by default. The SAA may then delegate the entitlement by assigning it to an authorized account administrator (AA).

Once the SAA has been notified that the API Console Entitlement Request has been completed,  the API Console entitlement can be added to appropriate User Accounts at your firm. That API User will then have access to the API Console app on FINRA Gateway and can create API Credentials on behalf of the firm. The API Console entitlement is the only entitlement required to access the API Console. Optionally, the SAA/AA may wish to entitle the API User's account with the E-Bill Invoices entitlement if the user is authorized/responsible for reviewing/paying invoices for any fees associated with the FINRA API Service.

Here are some important considerations when entitling user accounts with access to the FINRA API Console app:

  • Only users that have the authority to bind the organization to the FINRA API Terms of Service and the payment of any fees associated with the use of the FINRA API Service should be granted access to the API Console app.
  • All fees associated with the use of the API Service will be invoiced through E-Bill, thus it may be appropriate to add the E-Bill Invoices entitlement to an API User account.

Please reach out to the API team if you have any questions regarding the API Console entitlement process. 

Note: The above steps are ONLY for the access to the API Console application. Refer to this for access to other FINRA Gateway applications. 

 

Affiliate Program

The FINRA API Platform allows affiliated FINRA member firms to use the FIRM API Credential without a fee, provided the parent firm maintains an active PAID credential. Only the firm identified as the parent will receive the API invoice on a monthly basis. Affiliated firms, however, are accountable for monitoring their data usage and will incur charges for any overages. Before establishing the parent-affiliate relationship, the following requirements must be met:

  1. All firms must be registered in the CRD System as affiliates.
  2. All firms must request access to the FINRA API Console using the API Console Entitlement Request Form.
  3. All firms must have an active FIRM API Credential in production.

Once these requirements are met, the SAA of the parent firm can contact API Support to establish the parent-affiliate relationship. 

Both parent and affiliate firms can create up to five FIRM credentials each, and each FIRM Credential has a data limit of 10GB per month. Monitoring data usage for each credential is possible via the API Console. It's crucial for affiliated firms to manage their data usage within the designated limits to avoid overage charges. To learn more about data overage fee see FAQs here. Once the parent-affiliate relationship is established, it cannot be changed except in cases of organization changes such as mergers or acquisitions.

Info for Other Organizations

Organization's within the financial services industry, that are not regulated by FINRA, can still access the FINRA API platform by following the steps outlined here.

The first step is to determine if your organization has a previous relationship with FINRA, defined as having a signed FINRA Entitlement Agreement (FEA) in place. Your organization will also have an Organization ID provided by FINRA and a designated Account Certification Representative(CRep) who is also an Account Administrator(AA) -- CRep(AA) -- for your organization.

If you are unable to determine if you organization has a FINRA Entitlement Agreement in place, contact the FINRA Support Center at (301) 869-6699.

If your organization does not have a previous relationship with FINRA, then step one is requesting onboarding to the FINRA Entitlement Program for the API Platform.

To request onboarding an officer of your organization should complete and submit a FINRA Entitlement Account Administrator request.This request will be processed by the FINRA Entitlement Team within 3 business days and the individual designated as the Account Administrator (AA) and Certification Representative (CRep) -- CRep(AA) -- will receive an email when their FINRA Entitlement Admin Account has been created. Please visit FINRA.org for more information about the FINRA Entitlement Program and the FINRA Account Management System.

Once the CRep(AA) has been notified that the FINRA Entitlement Account Administrator request has been completed, the  API Console entitlement can be added to appropriate User Accounts at your organization (see the Account Management User's Guide). That user will then have access to the API Console app on FINRA Gateway and can create API Accounts on behalf of the organization. The API Console entitlement is the only entitlement required to access the API Console. Optionally, the CRep(AA) may wish to entitle the API User's account with the E-Bill Invoices entitlement if the user is authorized/responsible for reviewing/paying invoices for any fees associated with the FINRA API Service.

Here are some important considerations when entitling users with access to the FINRA API Console app:

  • Only users that have the authority to bind your organization to the FINRA API Terms of Service and the payment of any fees associated with the use of the API Service should be granted access to the API Console app.
  • All fees associated with the use of the API Service will be invoiced through through FINRA's E-Bill app on FINRA Gateway, thus it may be appropriate to add the E-Bill Invoices entitlement to an API User account.
  • the E-Bill Invoices entitlement to an API User account.

Please reach out to the API team if you have any questions regarding the API Console entitlement process. 

Note: The above steps are ONLY for the access to the API Console application. Refer to this for access to other FINRA Gateway applications. 

If your organization has a previous relationship with FINRA, defined as having a signed FINRA Entitlement Agreement (FEA) in place and a designated Certification Representative (CRep) who is also an Account Administrator (AA) -- CRep(AA) --, then that CRep(AA) should request  that the FINRA Entitlement Team assign the API Console Entitlement to their FINRA Entitlement Admin Account. This step is required because as an extra level of security, FINRA has not automatically assigned the API Console Entitlement to AA Admin Accounts.

To request access to this entitlement the CRep(AA) of your organization should complete and submit an API Console Entitlement Request.This request will be processed by the FINRA Entitlement Team within 3 business days and the CRep(AA) will receive an email indicating that the API Console entitlement has been assigned to their Admin account. Please note that the API Console entitlement is assigned to the CRep(AA) who filled out the form by default. The CRep(AA) may then delegate the entitlement by assigning it to another authorized account administrator(AA).

Once the CRep(AA) has been notified that the API Console Entitlement request has been completed, the  API Console entitlement can be added to appropriate User Accounts at your organization (see the Account Management User's Guide). That user will then have access to the API Console app on FINRA Gateway and can create API Accounts on behalf of the organization. The API Console entitlement is the only entitlement required to access the API Console. Optionally, the CRep(AA) may wish to entitle the API User's account with the E-Bill Invoices entitlement if the user is authorized/responsible for reviewing/paying invoices for any fees associated with the FINRA API Service.

Here are some important considerations when entitling users with access to the FINRA API Console app:

  • Only users that have the authority to bind your organization to the FINRA API Terms of Service and the payment of any fees associated with the use of the API Service should be granted access to the API Console app.
  • All fees associated with the use of the API Service will be invoiced through FINRA's E-Bill app on FINRA Gateway, thus it may be appropriate to add the E-Bill Invoices entitlement to an API User account.

Please reach out to the API team if you have any questions regarding the API Console entitlement process. 

Note: The above steps are ONLY for the access to the API Console application. Refer to this for access to other FINRA Gateway applications. 

The API Console

The API Console is a FINRA Gateway hosted app that provides a fully automated, self-service API credential management capability to FINRA’s API customers.

The process for accessing the API Console depends on whether you are affiliated with an organization regulated by FINRA, affiliated with an another organization not regulated by FINRA (e.g. vendor, service provider, insurance company), or an individual just interested in learning about the API Platform and testing it out, or using the platform for your own non-commercial purpose.

The sections below describe the two key concepts necessary for understanding how access to the API platform is determined(API User Types and API Credential Types), and provide detailed instructions for getting started with the API console depending on your role and purpose.

Please feel free to contact the API Team with any questions regarding the API Console or for a demonstration of its capabilities.

API User Types

You are a Firm User if you are affiliated with an organization regulated by FINRA such as broker-dealer or a dually registered broker-dealer/investment advisor.

You will obtain access to the FINRA API Console via your firm's designated Super Account Administrator (SAA) or an Account Administrator (AA).

If your firm is new to the API platform, the firm's SAA will first need to request that the API Console entitlement is assigned to the SAA's FINRA Entitlement Admin Account. Please direct the SAA to this page for specific details on getting access to the API Console Entitlement from the FINRA Entitlement team.

Once the SAA's Admin Account is assigned the API Console entitlement, the SAA will authorize your access to the API Console by either creating a FINRA Gateway User Account for you with the API Console entitlement, or by adding the API Console entitlement to your existing FINRA Gateway User Account.

If you have responsibility for reviewing/paying invoices associated with the FINRA API Platform via via FINRA's E-Bill application (also accessed via FINRA Gateway), the SAA will also have to add the E-Bill Invoices entitlement to your account. Please discuss this need with your SAA.

Once your account is created/update you can login to the console by selecting the Console button in the navigation bar. This will redirect you directly to the API Console app in FINRA Gateway.

As a Firm user you will be able to provision three types of API Credentials:

  • Firm Credential
  • Public Credential
  • Test Credential

See the API Fee Page for more details on the capabilities provided by each type of credential.

You may wish to create an Individual API User Account to begin testing and learning about the API Platform, before requesting access to the API Console via your firm SAA. This is possible by following the instructions for the Individual User Type below and is a good way to get started quickly. However, a Firm Credential is the only way to get access to data associated with your specific firm, such as registration data, and the Individual Account only allows provisioning of Public and Test Credentials.

 

TIPS:

  • If you do not know who the SAA is for your firm, contact the FINRA Support Center at (301) 869-6699.
  • If you create an Individual API User Account to get started, you will still need to request a Firm User Account from your SAA to access Firm information and other datasets. An Individual Account cannot be upgraded to a Firm Account.

The Organization Credential type is available to other organizations not regulated by FINRA, including product manufacturers (example insurance companies, mutual fund organizations), transfer agents, clearing firms, vendors and service providers. 

You will obtain access to the FINRA API Console via your organizations's designated Account Administrator (AA).

If your organization does not have a previous relationship with FINRA, then step one is to have an officer of your organization request onboarding to the FINRA Entitlement Program for the API Platform.

A previous relationship with FINRA is defined as having a signed FINRA Entitlement Agreement in place. Your organization will also have an Organization ID provided by FINRA and a designated Account Certification Representative(CRep) who is also an Account Administrator(AA) for your organization. Please direct an officer to this page for specific details on requesting onboarding which includes designating an individual to be an AA and CRep -- CRep(AA) -- for your organization.

If your organization has a FINRA Entitlement Agreement in place but is new to the API platform, then the CRep(AA) will first need to request that the API Console entitlement be assigned to their FINRA Entitlement Admin Account. Please direct the CRep(AA) to this page for specific details on getting access to the API Console Entitlement from the FINRA Entitlement team.

Once the CRep(AA) Admin Account is assigned the API Console entitlement, the CRep(AA) will authorize user access to the API Console by either creating a FINRA Gateway User Account for you with the API Console entitlement, or by adding the API Console entitlement to your existing FINRA Gateway User Account.

If you have responsibility for reviewing/paying invoices associated with the FINRA API Platform via FINRA's E-Bill application (also accessed via FINRA Gateway), the CRep(AA) will also have to add the E-Bill Invoices entitlement to your account. Please discuss this need with your CRep(AA).

Once your account is created/update you can login to the console by selecting the Console button in the navigation bar. This will redirect you directly to the API Console app in FINRA Gateway.

As an Organization User you will be able to provision three types of API Credentials:

  • Organization Credential
  • Public Credential
  • Test Credential

See the API Fee Page for more details on the access provided by each type of credential.

You may wish to create an Individual API User Account to begin testing and learning about the API Platform, before requesting access to the API Console via your organization CRep(AA). This is possible by following the instructions for the Individual User Type below and is a good way to get started quickly. However,  the Individual Account only allows provisioning of Public and Test Credentials, and an Organization Credential will be required to access the capabilities associated with the Organization Credential Type.

 

TIPS:

  • If you do not know if your organization has a FINRA Entitlement Agreement in place, or who the CRep(AA) is for your organization, contact the FINRA Support Center at (301) 869-6699.
  • If you create an Individual API User Account to get started, you will still need to request an Organization User Account from your CRep(AA) to access the capabilities associated with an Organization Credential Type. An Individual Account cannot be upgraded to an Organization Account.

You are an Individual User if you plan to access the API Platform for your own purpose, regardless of your affiliation with a firm or other organization.

You will obtain access to the API Console by creating an Individual API User Account by selecting the Console button in the Navigation Bar and then selecting the Create Account Here link on the FINRA login page.

You will receive the credentials for your Individual User Account via email including a password reset link.

NOTES:

  1. Check your SPAM filter or JUNK MAIL folders for the credential email
  2. The password reset link expires in 1 hour so prompt action is required. If the link expires you must contact the FINRA Support Center at (301) 869-6699 to have another password reset link sent to your email address.
  3. The account password expires and will have to be changed every 120 days. Obtain a new password here.

Once your account is created you will be redirected directly to the API Console app in FINRA Gateway. 

As an Individual User you will be able to provision two types of API Credentials:

  • Public Credential
  • Test Credential

Individual Accounts are intended for developers who want to begin exploring and testing the API Platform before committing to an integration effort, and for individual investors, researchers, etc. that need access to public data provided by FINRA via the API Platform. It is not intended for commercial purposes at this time.

Important Information for Users Who Have Previously Created Test Credentials

Existing API Users who have created Test Credentials via the "Request Test Access" button on developer.finra.org (no longer available) can use those credentials to access the API Console as an Individual User without further action. There is no need to create an additional Individual Account to access the API Console, and the FINRA Login service will not allow multiple Individual Accounts to be tied to the same e-mail address.

Your existing Test Credentials can also continue to be used to access the mock data via API until 3/31/2022. At that time the Test Credential will convert to an Individual Account and can only be used to login to the API Console.

Therefore, once you have access to the API Console using your existing Test Credentials you should provision a new Test Credential via the API Console and use the new credential for your testing purposes. You may also provision a Public Credential to access the available public data via the console.
 

TIP: If you are having difficulty logging in to the API Console using your Test Credential contact, the FINRA Support Center at (301) 869-6699.

API Credential Types

The Firm Credential Type can be provisioned by Firm Users who have been granted access to the API Console by the firm's SAA or AA.

See the Fee Structure page for details on the capabilities offered by the Firm Credential.

The Organization Credential Type can be provisioned by Organization Users who have been granted access to the API Console by the organization's AA.

See the Fee Structure page for details on the capabilities offered by the Organization Credential.

The Public Credential Type can be provisioned by Firm, Organization, and Individual Users who have access to the API Console.

See the Fee Structure page for details on the capabilities offered by the Public Credential.

The Mock Credential Type can be provisioned by Firm, Organization, and Individual Users who have access to the API Console.

Each dataset delivered via the API platform will have mock data available. The mock data will be a representative sample but may be randomized. This data can be used by developers to evaluate available APIs and to to test their integrations with the FINRA API platform.

 

See the Dataset Catalog for details on available datasets.

A Mock Credential can only be used with mock datasets. This means the dataset name must have "MOCK" appended to the end of the name. (e.g. preRegistrationIndividualMock). 

Firm and Organization credentials now CAN also access mock datasets.

Creating an API Credential

An API Credential is required to make API requests on the FINRA API platform. It is the equivalent of a username and password for logging into a website or application, but is used in the Authorization header of all API requests to authenticate the API client (AuthZ) with the API platform, and to authorize (AuthN) the API client to access the data and services on the platform.

Each API credential you create will have an API Client ID (created by the API Console) and an API Client Secret (provided by you when activating the API credential as described below). Each API credential is linked to the UserID you used to login to FINRA Gateway and access the API Console app.

Once you have access to the API Console and have logged in to FINRA Gateway, you will see the API Credentials view with an empty My Credentials tab.

api console screenshot

 

To create your first credential select either ADD API CREDENTIAL button to access the API Credential Details form.

api credential details

Complete this form, agree to the FINRA API Terms of Service and select the CREATE button to submit the request.

Once created the new credential will be added to the credential list in the My Credentials tab.

api credential list

Note that the API Secret for the new credential is initially shown as Expired. This is because an API Secret create link is sent to the email address of the API Console user (subject: FINRA API Developer Center – Action Required) and must be used to choose an API Secret and complete the process of activating the API Credential. See the API Credential Creation Tips below for important information about activating the API Credential.

When you have received the activation email select the Create API Client Secret button in the message to be taken to the FINRA Reset Password page.

reset password page

Enter the API Client ID in the User ID text box and provide your chosen password (API Client Secret). Select the SAVE button and the API Credential will now be activated.

api credential list
 

Congratulations you have created your first API Credential for use with the FINRA API Platform. Now review these details to put the new credential to work.

IMPORTANT: API Credential Creation Tips
  1. The API Credential name is an alias that you provide to help you remember your use intention for the credential. It can be changed in the API Console at any time (feature coming soon).
  2. The Type dropdown allows you to select the type of credential you would like to create. The allowable selections are based on your user type. For example,  if you are logged-in to the API Console as an Individual User, the allowable selections will include test and public.
  3. The Total Fee Per Month will change to reflect any fees associated with a credential type. When you select the SAVE button to create a credential with an associated fee, your organization will be invoiced for that credential on E-Bill.
  4. The API Secret create link sent via email EXPIRES in 24 hours. If the link expires, you will need to contact the API Support team to have another create link sent via email (a client secret reset feature is coming soon).
  5. You will also receive the API Client Id in a separate email (subject: FINRA API Developer Center – Important Information). You will need the API Client Id when activating the API credential.
  6. Look in your Junk Mail/Spam Filters for the FINRA API email messages if you do not receive them within a few minutes. If you do not receive the email messages within an hour contact the API Support team to let us know.
  7. When activating the API Credential and choosing an API Secret note that the User ID you are asked to provide is the Client ID shown in the My Credentials tab for the API Credential you are activating and NOT the User ID you used to login to FINRA Gateway.
  8. Note that the API Secret expires in one year and will need to be reset it via the API Console (feature coming soon).

API Platform Basics

The sections below provide an overview of the basic features of the FINRA API Platform.

Authorization

The FINRA API Platform authentication and authorization scheme is based on OAuth 2.0.

OAuth 2.0 enhances security by replacing the use of long-lasting credentials with limited life span tokens, reducing the potential of exposing an API Credential.

The overall authentication flow is:

  1. API client sends a  POST request to the FINRA Identify Platform (FIP) using the API Client ID and API Client Secret associated with an API credential (created via the API Console) as a Basic Auth token in the Authorization Header.
  2. Use "access_token" returned from FIP as a Bearer token in the Authorization Header to invoke the required FINRA API endpoint(s).
  3. Use "expires_in", returned from FIP as the number of seconds until expiry, to determine the expiration time of the "access_token" and regenerate the access_token via another FIP request before this time, or cache the access_token for 30 minutes before regenerating.

OAuth 2.0 Flow

 NOTES:

  • The FIP endpoint for generating an access_token is: https://ews.fip.finra.org/fip/rest/ews/oauth2/access_token?grant_type=client_credentials.
  • API Client must use a POST request
  • The Basic Authorization header sent to the FIP access_token endpoint contains the word Basic followed by a space and a base64-encoded string containing "apiclientid:apiclientsecret".  Note that the colon ":" is required in the token string before it is base64 encoded.
  • The API Client ID and API Client Secret are provisioned through the API Console.
  • The access_token returned by FIP is used as a BEARER token in the Authorization header (Bearer access_token) of API requests and not a Basic Auth token.
     
Request
curl --location --request POST "https://ews.fip.finra.org/fip/rest/ews/oauth2/access_token?grant_type=client_credentials" --header "Authorization: Basic NzVjNzQ2YTEwNjY2NGJjZmJiNGM6UkVWIGluIGdvIGnRzIQ=="

 

Response
{
    "access_token": "*AAJTSQACMDIABHR5cGUAA0pXVAACUzEAAjAx*eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ZXlKMGVYQWlPaU pLVjFRaUxDSmxibU1pT2lKQk1USTRRMEpETFVoVE1qVTJJaXdpWVd4bklqb2laR2x5SW4wLi56RlNXS09XZklKX1FJT3htWEZtalpB LjF4LVVCMF9OdG85WmhkZlRvTW10dXNNZkxGMUN6MS0tVVVKYTYzYXBwdm8xWExVYzRLXy1raUVEOHFpRXpLZU14aUtLWDc1eTRwcVc4eVlDMs",
    "scope": "any",
    "token_type": "Bearer",
    "expires_in":"43170"
}

 

Request Headers

The API platform supports the following headers in all API requests:

header required description default
Authorization required Contains the word Bearer followed by a space and an access_token generated from the FINRA Identity Platform (FIP) n/a
Accept optional

Can be used to specify a format for the data returned. Supports (application/json and text/plain). If the native data format cannot convert between JSON/CSV, then a status code of 400 will be returned. If an unsupported MIME type is supplied, then a 406 is returned.

 text/plain
Data-API-Version optional Used to specify version of the API to use. version 1

Response Headers

All responses to API requests may include the following response headers:

header description
Content-Type Set to match the value of the request's Accept header unless an error occurred, in which case it will be set to application/json. Possible values include application/json and text/plain.
FINRA-api-request-id This is the unique tracking id for the request made. Use this if contacting FINRA about this request.
Record-Total Total records found at the time of the request. Use this value when paging through large datasets to determine when all data has been retrieved.
Record-Offset Set to match the offset value provided with the request.
Record-Limit Set to match the limit value provided with the request or the platform maximum limit, whichever is smaller. 
Total-Records-On-Page Total number of records returned for this page. This will be default number of records for the page, except for the last page, this might be less than the default.
Record-Max-Limit  Set to the maximum number of records that will be returned by the platform, regardless of the size of the response payload. Use this header to build an API client that can adapt to future record limit value changes.
Response-Payload-Max-Size  Set to the maximum payload size (in MB) that will be returned by the platform, regardless of the number of records returned. Use this header to build an API client that can adapt to future response payload size changes.
Location Contains a URL that will be used as the second leg of the operation to check the status of the asynchronous request.

Platform Usage Limits

FINRA reserves the right to limit the number of requests made by an API Client, the number of records returned in a response or the size of a response payload, as well as other parameters as necessary to ensure the reliability, performance, and integrity of the API platform.

The API platform enforces the following throttling limits:

  1. Sychronous requests:   20 requests per second per IP address. 
  2. Asynchronous requests: 20 requests per hour per dataset per API account

Maintaining a reliable, performant API platform is a joint responsibility of the FINRA API team and all API users. Adhering to the following guidelines will help ensure the integrity of the platform:

  1. Only access as much data as needed to accomplish your objective or use case. Use compare filters and the other POST filter parameters to reduce the amount of data returned in a response whenever possible.
  2. Utilize a GET request only when trying to sample a small number of records using the limit parameter. Otherwise, the POST request should be used in order to filter the data on each request. NOTE: This guideline does not apply when using asynchronous requests and polling for the async result or accessing the async response file, which should utilize GET requests.
  3. Understand the data you are trying to access. In many cases, the data is static after a period of time and there is no need to repeatedly download historical data. For example, most of the data available via the Equity API is generally static after one year. Therefore adjust your access patterns to avoid downloading historical data over one year old on a recurring basis.
  4. Develop sound algorithms that access available data in smaller traunches rather than simply accessing as many records as possible on each requests. Each dataset offers a number of fields that can be used in filters such as trade dates, week and month start dates, tier levels, CRD numbers, etc.
  5. Utilize asynchronous requests whenever accessing a large number of records as this will allow you to obtain more records per API request while helping to protect the platform.
  6. Utilize asynchronous requests in combination with the available historical datasets (e.g. weeklySummaryHistorical).
  7. Brute force algorithms that simply run 24*7*365 and continuously access the same data are never appropriate and are subject to being blocked.

The API platform enforces two limits regarding the maximum amount of data returned by an API request:

  • Maximum Record Limit: the maximum number of records returned by an API request. 
  • Maximum Payload Size: the maximum payload size returned in the response payload.
  • Whichever limit is reached first will govern the amount of data returned. 

 The API platform limits the number of records that can be returned from a individual API request:

  1. Synchronous requests will return a maximum of 5000 records for any one API request
  2. Asynchronous requests will return a maximum or 100,000 records for any one API request.

NOTE : The API record limit defaults to 1000 unless a larger number is specified using the limit query string (GET) or request parameter (POST).

The API platform limits the amount of data that can be returned in the body of an individual API request:

  1. Synchronous requests will return a maximum of 3MB of data in the response body of any one API request.
  2. Asynchronous requests can return any amount of data and are not limited to the 3MB response body size.

When working with large datasets that contain more records than the maximum record limits (5,000 synchronous /100,000 asynchronous) the API user must design an algorithm to access the data in traunches that honor the platform usage limits.

The key request parameters that facilitate accessing data in traunches include:

  • Limit parameter: Number of records to return. The default value (if limit parameter is not provided on a request) is 1000. 
  • Offset parameter: Record number to start with (exclusive). For example, if the offset is 0 and the limit is 20, then records 1 to 20 are returned for a total of 20 records. If the offset is 10 and the limit is 10, then records 11 to 20 are returned.

IMPORTANT:

The offset parameter has a maximum value of 500,000. The effect of this limit is that a maximum of 505,000 records can be accessed synchronously, and a maximum of 600,000 records can be accessed asynchronously, without the use of additional filters. For example, the weeklySummary dataset contains more than 20 million records. Because of the 500,000 offset limit it is not possible to access all 20M+ records simply by increasing the offset parameter until all data is accessed.

Instead the API user would need to utilize filters in conjunction with the limit and offset parameters to access the entire range of records in the dataset. In the case of the weeklySummary dataset, for example, the API user might filter the dataset by the weekStartDate and tierIdentifier fields to reduce the overall size of the data and then page through that traunch of data using the limit and offset parameters as needed. The data access algorithm can then step through the available weekStartDate and tierIdentifier values to access the entire dataset in a manner consistent with the platform usage limits.

There are a number of  response headers that can be used to page through larger datasets in compliance with the response size and offset limits, including:

  • Record-Total response header: Total records found at the time of the request. Use this value when paging through large datasets to determine when all data has been retrieved.
  • Record-Offset response header: Set to match the offset value provided with the request.
  • Record-Limit response header: Set to match the limit value provided with the request or the platform maximum limit, whichever is smaller. 
  • Record-Max-Limit response header: Returns the current maximum number of records that will be returned by the API platform. Use to build a flexible integration that can adapt to future record limit changes.
  • Response-Payload_Max_Size response header: Returns the current maximum payload size (in MB) returned by the API platform. Use to build a flexible integration that can adapt to future payload response size changes. Applies only to synchronous API requests.

Notes:

  1. To maximize the number of records returned in a response minimize the number of fields you return and use the text/plain Accept header on  your requests whenever possible (e.g. the Equity datasets support text/plain).
  2. API clients should count the number of records returned in each response in order to ensure all expected data is returned, and to adapt future requests if less data than expected was returned because the record and/or the response payload size limits are reached.

Time Zones

All date and time related fields in the API requests are interpreted as Eastern Standard Time. Date/time fields returned in an API response are returned in the same time zone as the raw data when initially stored. No time zone conversion is performed.

Troubleshooting

The following API response codes are returned by the Data API platform:

HTTP status code Reason
200 OK
201 Created
204 No Content
400 Bad Request
410 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
406 Not Acceptable
409 Conflict
415 Unsupported Media Type
500  Internal Server Error
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout


The 200 status code is returned for successful requests even when the request returns no data. For requests receiving application/json output the response body will contain any empty JSON array. For requests receiving text/plain output the response body will contain the header row with no data rows.

The 4xx status codes are returned when a problem exists with a request. The response body will contain a JSON structure with additional information about the error.

5xx status codes are returned when there is a service level error that cannot be identified. The API support team is notified of all error conditions therefore it is not necessary to report these errors via the Support Center, unless the error persists for an extended period of time.

{
"statusCode": 400,
"statusDescription": "Bad Request",
"requestId": "ba7c841a-5322-4e07-863a-a44f09a5fc59",
"message": "Invalid date field format. Must be yyyy-MM-dd or yyyy-MM-dd HH:mm:ss.SSS",
"dataRequest": {
"action": "POST",
"internalParams": {},
"datasetGroup": "OTCMarket",
"datasetName": "weeklySummary",
"fields": [],
"dateRangeFilters": [
{
"description": "Filter used to specify a date time range of format (yyyy-MM-dd | yyyy-MM-dd HH:mm:ss(.SSS)). For example, 2017-02-10 21:30:23. Start and End dates are inclusive.",
"startDate": "2017-01-01",
"endDate": "2399-12-31",
"fieldName": "weekStartDate"
}
],
"domainFilters": [],
"compareFilters": [
{
"description": "Filter used to compare field values using traditional equal, not equal, gt, lt, gte, or lte logic.",
"fieldName": "tierIdentifier",
"fieldValue": "T2",
"compareType": "EQUAL"
},
{
"description": "Filter used to compare field values using traditional equal, not equal, gt, lt, gte, or lte logic.",
"fieldName": "weekStartDate",
"fieldValue": "201-03-11",
"compareType": "EQUAL"
},
{
"description": "Filter used to compare field values using traditional equal, not equal, gt, lt, gte, or lte logic.",
"fieldName": "summaryTypeCode",
"fieldValue": "ATS_W_SMBL",
"compareType": "EQUAL"
},
{
"description": "Filter used to compare field values using traditional equal, not equal, gt, lt, gte, or lte logic.",
"fieldName": "issueSymbolIdentifier",
"fieldValue": "ELAN.V",
"compareType": "EQUAL"
}
],
"sortFields": [
"issueSymbolIdentifier",
"marketParticipantName"
],
"limit": 1000,
"offset": 0,
"delimiter": ",",
"quoteValues": true,
"format": "text/plain"
}
}

 

Service Availability

The API platform is available 24/7. All scheduled maintenance is done outside the window of 8am-8pm on weekdays.

Base URL

  PROD QA Test
Base URL https://api.finra.org https://api-int.qa.finra.org

 

 

Important:

All API requests must use HTTPS protocol.

QA Test Environment

The FINRA API Platform has added a QA Test Environment to help customers identify and resolve any issues or bugs in the integration process prior to production deployment.  

Key Features and Benefits:

  • Seamless Integration Testing: The QA Test Environment replicates all the functionality available in the production environment, providing you with a reliable and accurate testing environment.
  • Easy Access: Accessing the Test Environment is simple and straightforward. You can create API credentials through the user-friendly API Console in our dedicated FINRA Gateway (QA). To request FINRA Gateway (QA) account, the SAA/AA must complete and submit an API Console Test Environment Account Request and meet the following requirements.
    • The firm/organization must already be onboarded to production. To learn more about how to get access to API Console in production, see here.
    • An Individual whose test account is being requested must already have a FINRA Gateway account with an entitlement to access API Console in production
    • At least one Firm or Organization credential must be provisioned using the API Console in FINRA Gateway production for the firm/organization. To learn more about how to create credential see here.
  • Cost-Effective Testing: We understand the importance of efficient testing without incurring additional costs. Therefore, creating and using credentials in the Test Environment are entirely free of charge.
  • Data Limit Exemption: Usage in the Test Environment does not count against the 10GB monthly data limit per credential. This allows you to thoroughly test your integrations without any limitations.
  • Data Refresh: To ensure the utmost accuracy, data in the Test Environment is refreshed from the production environment twice a year. Please note that Social Security Numbers (SSNs) and Dates of Birth (DOBs) are obfuscated, while the remaining Personally Identifiable Information (PII) remains consistent with the production environment.
  • Availability: While we consistently work towards ensuring high availability, the environment may experience intermittent periods of downtime due to scheduled releases and essential maintenance. We are committed to minimizing disruptions and will make every effort to provide advance notice whenever possible to keep you informed about any scheduled downtime.

Environment links: