FACTSET ID Lookup API Software
FAQs
- Q: What is the authentication method for the FactSet ID Lookup API?
- A: The API authenticates using API keys. A detailed authentication process can be found in the provided guide.
- Q: What are the core functionalities of the FactSet ID Lookup API?
- A: The API leverages FactSet’s search functionality to return tickers, company names, and unique identifiers. It also offers type-ahead functionality for quick results and easy integration with web applications.
- Q: What is the logic behind how results are ranked?
- The ranking is based on several variables. Generally, string matching affects the ranking depending on how much the search term matches the results. In addition, each entity type has its own unique variables that can affect the ranking. For example, equities use market cap and primary listing.
PRODUCT INFORMATION
Document Organization and Audience
This document describes how to use FactSet ID Lookup API. You should be familiar with JSON, API, and Web Services. This document will describe the syntax needed for proper request formatting as well as the rules for processing responses.
Trademarks
FactSet is a registered trademark of FactSet Research Systems, Inc. All other brand or product names may be trademarks of their respective companies.
Overview
Introduction to FactSet ID Lookup API
FactSet Identifier Lookup API exposes the service that powers the search functionality in FactSet WorkStation and FactSet Web. Clients can leverage this API for their search functionality to return tickers, entity names, and other identifiers that FactSet supports.
Sample Data Flow
Core Functionality and Benefits
- Leverages FactSet’s powerful search functionality to return tickers, company names and unique identifiers for FactSet data
- Type-ahead functionality to display related results quickly
- Simple integration with your existing web applications
Authentication
- The API authenticates using API keys.
- Client would be provided with a FactSet login to Developer’s Portal (https://developer.factset.com/).
- End user must generate an API key from the Developer portal.
- The key is generated once and cannot be retrieved again. User needs to take a copy and store the API key.
- The complete guide to the authentication process to the service can be found here:
Certificates and Certificate Chains
FactSet highly discourages hardcoding reliance on any particular certificate or advertised certificate chain into applications. FactSet expects clients to rely on Public Key Infrastructure verification and validity of the certificates:
- FactSet’s Certificates will change over time as they are renewed and the complexity of the algorithms employed increases (i.e. SHA-2 rather than SHA-1 signatures). This is the constant evolution of security as old security algorithms are retired and new security algorithms are included. Often these certificates get updated on a rolling multi-year basis. Validating a certificate dynamically during TLS connect must be incorporated by the client as a necessary practice.
- FactSet’s Certificate chains, including intermediate Certificate Authorities, may change over time, and it is important that clients dynamically validate FactSet’s certs against a modern CA trusted root certificate store. FactSet’s current root certificate is Thawte Primary Root CA.
Security Protocols
Clients should not hardcode dependencies on any specific security protocol as FactSet is continuously reviewing security policies and reserves the right to disable support for older security protocols with short notice. The current supported protocols are TLSv1.1 and TLSv1.2 but at a future date, these may be replaced with future versions. Clients should make sure that their software can handle ever changing Security Protocols.
Request Limits
There is a limit on how many requests each client can make within specific durations. This is to ensure the API is running optimally and mitigate any impact to other FactSet services. The API offers three tiers of request limits. All clients who are using this API will get the default tier. Clients who are interested in tier B should discuss the commercials with their FactSet sales rep.
| Tier | # of requests/sec | # of requests/minute | # of requests/hour |
| Default | 20 | 100 | 2,000 |
| Tier B | 200 | 1,000 | 20,000 |
Sample Scenarios
Depending on the tier, the API would respond with a 429 code depending on which time duration limit they reach first. The limit starts at the time the first request is made. The cached time would reset after an hour, even if the client does not reach the limit.
- [Client A: default tier] At 15:22:15, client reaches the limit of 100 requests per minute. The API would respond with a 429 on subsequent requests until the restriction is lifted a minute later at 15:23:15
- If the same client reaches the 2,000 requests per hour limit at 15:44:00, then the limit would not be lifted until 16:44:00.
API
FactSet ID Lookup API will accept POST requests in a JSON-formatted request body.
URL
- FactSet provides production environment that can be used for production access. The following table shows the URL needed for each system.
| Type | Host Name | Service | Example URL1 |
| Produc tion | api.factset.com | idsearch | https://api.factset.com/idsearch/v1/idsearch |
Query
Query is an array containing search query objects with parameters to run concurrently. This is the request sent via the API to look for a specific set of identifiers.
Query
The query object contains the search term and filters defined by the end user. Each query object contains the following parts:
| Names | Description | Examples and Notes |
| patterns | This is the string or keyword being searched on. Concurrent searches for multiple patterns
is NOT supported |
FactSet Research Systems is treated as a single search term but not as FactSet OR
Research OR Systems |
| entities | The asset class that is being search against | List of available asset classes are available in Section 2.2.4 |
| filters | Helps narrow down the search results through including and/or excluding parameter.
Filters are specific depending on the asset class |
List of available filters are listed in Section 2.2.4 |
| search_fields | Limit results to these symbology type:
• Symbol • Entity name • CUSIP |
This parameter is only available for these asset classes:
• Equities • Private Companies • Bonds • ETFs • Futures • Mutual Funds |
Filters
The filter object (if used) must contain one or both of the following:
1 The example URLs demonstrate the different services assigned to production and beta. The URLs given above may not be valid. For example, the query string is missing in the above example.
- Include – Specifies criteria to selectively include specific datasets in the results. Each dataset has its own relevant fields, such as equityType, isPrimary, region, etc. For each field, provide an array of values you wish to filter on. For example, specifying [“US”, “GB”] for the region field will include documents where the region is either the United States or Great Britain. The values in each array are combined using an OR operation, meaning any dataset matching one or more of these values will be included in the results.
- Exclude – Specifies criteria to exclude certain datasets from the results. Each dataset has its own relevant fields, such as equityType, isPrimary, region, etc. For each field, provide an array of values you wish to filter out. For example, specifying [“US”, “GB”] for the region field will exclude documents where the region is either the United States or Great Britain. The values in each array are combined using an OR operation, meaning any dataset matching one or more of these values will be excluded from the results.
Clients must also have these settings for the include and exclude filters. The full list of acceptable field, entities and values is available in Section 2.2.4
- field – string containing the field name to filter on. Each asset class has its own set of fields (i.e. “equity_type”, “is_primary”, “region”, etc).
- entity – string containing the asset class for the filter to be applied on. If not included or left empty, it will apply the filter against all asset class
- values – values you wish to filter on, as a comma-separated list. The values within this list are tied by an OR operation. o Example: an include filter with “values”: [“US”, “GB”] would include documents whose region values are either the United States or Great Britain. The possible values for regions are available in Appendix A
Sample Request Format
Acceptable Names and Values
Below is the list of supported names and values for each asset class and related filters:
| Asset
Class/”Entities” Description |
Asset Class/“Entities” Values | Fields | Field Values | Field Values Description |
| Bank Loans | bank_loans | |||
| Commodities | commodities | |||
| Continuous Evaluated Pricing | cep_bonds | |||
| Countries | countries | |||
| Deals | deals | |||
| Economic Reports | econ_reports | |||
| Economic
Series |
economic_series | |||
| Equities | equities | equity_type | EQ_Primary | Primary Market |
| EQ_PREF | Preferred
Equities |
|||
| EQ_RIGHTS | Rights | |||
| EQ_WARR | Warrants | |||
| EQ_DEPOS | Depository
Receipts |
|||
| EQ_DR_ADR | ADR | |||
| EQ_DR_GDR | GDR |
| EQ_DR_NVDR | NVDR | |||
| EQ_DR_ODR | Other DR | |||
| is_primary | 0 = false
1 = true |
|||
| region | See Appendix
A |
|||
| Equities Realtime | equities_realtime | |||
| ETFs | etfs | regions | See Appendix
A |
|
| ETFs Realtime | etfs_realtime |
| Exchange Rates Realtime | exchange_rates_realtime | |||
| Fixed Income | bonds | coupon | arbitrary value | |
| maturity_year | arbitrary year | |||
| 144a | 0 = false
1= true |
|||
| reg_s | 0 = false
1= true |
|||
| real_time | 0 = false
1= true |
|||
| terms | 0 = false
1= true |
|||
| Foreign
Exchange |
forex | |||
| Futures
(continuous) |
futures | |||
| Indices | Indices | is_primary | 0 = false
1= true |
|
| Indices
Realtime |
indices_realtime | |||
| Industries | industries | |||
| Markit Loans | markit_loans | |||
| Mutual Funds | mutual_funds | mf_type | MUT | Mutual Funds |
| MUT_OPEN | Open-end funds | |||
| MUT_CLOSED | Closed-end funds |
| Mutual Funds
Realtime |
mutual_funds_realtime | |||
| Ownership Holders | ownership_holders | |||
| People | people | |||
| Private Companies | private_companies |
| Private Equity/Venture Capital Firms | pevc_firms | is_child | 0 = false
1= true |
|
| is_shell | 0 = false
1= true |
|||
| Private Equity/Venture Capital Funds | pevc_funds | is_child | 0 = false
1= true |
|
| is_shell | 0 = false
1= true |
|||
| Region | regions | |||
| Yields | yields |
Settings
Allow users to adjust the behavior of the request and response.
| Name | Value | Description |
| result_limit | Arbitrary value | Number of results to be returned by search. Max number of results = 25*; default is 10 if field
is not used. |
Sample query
This example requests that only the top 25 results be returned.
Samples
Simple query
This simple query is requesting the top 10 matches in FactSet’s People database with the name Gates:
These are the top 10 results with Gates in the name. The value in the symbol is associated with the name of the related entity. This could be a ticker symbol for equities or FactSet unique identifier for other asset class like private company. Symbol is the only value that should be passed back to any FactSet services to retrieve data.
Example: if you want to retrieve the People Snapshot for Bill Gates, you should pass 00118X-E (and not Bill Gates, III) in the parameter for the FactSet service you are using.
Results
By default, the API returns 10 results per asset class that closely matches the query. For example, if the query requests for two “entities”, then the API would return 20 results. Below is the response for the sample query in section 2.3.1:
Sample query using a filter
In this example, the query is looking for bonds that have “US” in its name. We are also setting a filter to return bonds that have a 2021 maturity date.
This is the response from the query:
Sample query using OR logic
The OR logic is set by setting multiple values within the same block, separated by a comma. In this example, the query is searching for equities OR private companies that has the word air in its name. We are not setting any filters for this query.
This is the response for the query above:
Sample query using AND logic
In this example, the query is searching for fixed income that has the word life in its name. We are also setting an AND filter to only return those bonds that are offered as Reg S and have a 2020 maturity date.
This is the response for the query:
Sample query using both OR & AND logic
In this example, the query is searching for equities that has the word group in its name. We are only interested in Global Depositary Receipts (GDR) that are in Great Britain or Germany.
This is the response for the query:
Appendix
A1. Acceptable value for Region field
Below is the list of acceptable country codes for the Region field
| Country Code | Country Name |
| AF | Afghanistan |
| AL | Albania |
| DZ | Algeria |
| AD | Andorra |
| AO | Angola |
| AI | Anguilla |
| AG | Antigua and Barbuda |
| AR | Argentina |
| AM | Armenia |
| AW | Aruba |
| AU | Australia |
| AT | Austria |
| AZ | Azerbaijan |
| BS | Bahamas |
| BH | Bahrain |
| BD | Bangladesh |
| BB | Barbados |
| BY | Belarus |
| BE | Belgium |
| BZ | Belize |
| BM | Bermuda |
| BT | Bhutan |
| BO | Bolivia |
| BA | Bosnia and Herzegovina |
| BW | Botswana |
| BR | Brazil |
| BG | Bulgaria |
| KH | Cambodia |
| CM | Cameroon |
| CA | Canada |
| CV | Cape Verde |
| KY | Cayman Islands |
| TD | Chad |
| CL | Chile |
| CN | China |
| CO | Colombia |
| CK | Cook Islands |
| CR | Costa Rica |
| HR | Croatia |
| CW | Curacao |
| CY | Cyprus |
| CZ | Czech Republic |
| DK | Denmark |
| DO | Dominican Republic |
| EC | Ecuador |
| EG | Egypt |
| SV | El Salvador |
| EE | Estonia |
| FO | Faroe Islands |
| FJ | Fiji |
| FI | Finland |
| FR | France |
| GE | Georgia |
| DE | Germany |
| GH | Ghana |
| GI | Gilbraltar |
| GR | Greece |
| GT | Guatemala |
| GG | Guernsey |
| GY | Guyana |
| HN | Honduras |
| HK | Hong Kong |
| HU | Hungary |
| IS | Iceland |
| IN | India |
| ID | Indonesia |
| IR | Iran |
| IQ | Iraq |
| IE | Ireland |
| IM | Isle of Man |
| IL | Israel |
| IT | Italy |
| CI | Ivory Coast |
| JM | Jamaica |
| JP | Japan |
| JE | Jersey |
| JO | Jordan |
| KZ | Kazahkstan |
| KE | Kenya |
| KR | Korea, South |
| KW | Kuwait |
| KG | Kyrgyzstan |
| LA | Laos |
| LV | Latvia |
| LB | Lebanon |
| LR | Liberia |
| LY | Libya |
| LI | Liechtenstein |
| LT | Lithuania |
| LU | Luxembourg |
| MO | Macao |
| MK | Macedonia |
| MG | Madagascar |
| MW | Malawi |
| MY | Malaysia |
| MV | Maldives |
| MT | Malta |
| MH | Marshall Islands |
| MU | Mauritius |
| MX | Mexico |
| MD | Moldova |
| MC | Monaco |
| MN | Mongolia |
| ME | Montenegro |
| MA | Morocco |
| MZ | Mozambique |
| MM | Myanmar |
| NA | Namibia |
| NP | Nepal |
| NC | New Caledonia |
| NZ | New Zealand |
| NI | Nicaragua |
| NG | Nigeria |
| NO | Norway |
| OM | Oman |
| PK | Pakistan |
| PS | Palestine |
| PA | Panama |
| PG | Papua New Guinea |
| PY | Paraguay |
| PE | Peru |
| PH | Philippine |
| PL | Poland |
| PT | Portugal |
| PR | Puerto Rico |
| QA | Qatar |
| RO | Romania |
| RU | Russia |
| RW | Rwanda |
| KN | Saint Kitts and Nevis |
| LC | Saint Lucia |
| VC | Saint Vincent and the Grenadines |
| SA | Saudi Arabia |
| RS | Serbia |
| SC | Seychelles |
| SG | Singapore |
| SK | Slovakia |
| SI | Slovenia |
| ZA | South Africa |
| ES | Spain |
| LK | Sri Lanka |
| SD | Sudan |
| SZ | Swaziland |
| SE | Sweden |
| CH | Switzerland |
| SY | Syria |
| TW | Taiwan |
| TJ | Tajikistan |
| TZ | Tanzania |
| TH | Thailand |
| NL | The Netherlands |
| TT | Trinidad and Tobago |
| TN | Tunsia |
| TR | Turkey |
| TC | Turks and Caicos Islands |
| UG | Uganda |
| UA | Ukraine |
| AE | United Arab Emirates |
| EU | United Kingdom |
| GB | United Kingdom |
| UM | United States Minor Outlying Islands (the) |
| US | United States of America |
| UY | Uruguay |
| UZ | Uzbekistan |
| VU | Vanuatu |
| VE | Venezuela |
| VN | Vietnam |
| VG | Virgin Islands (British) |
| VI | Virgin Islands (U.S.) |
| YE | Yemen |
| ZM | Zambia |
| ZW | Zimbabwe |
A2. Response Codes
These are the response codes that the ID Lookup API returns:
|
429 |
Reached API limit as per section 1.4 |
| 500 |
Possible incorrect query format (e.g. missing comma, bracket pairs, etc.) |
Documents / Resources
 |
FACTSET ID Lookup API Software [pdf] User Guide ID Lookup API Software, Lookup API Software, API Software, Software |