Entity Search - API Parameters

PermID Entity Search API supports organizations,  equity instruments and quotes. The PermID Entity Search API allows you to search in two ways:

  • by providing the PermID of a single/specific entity (PermID Lookup).
  • by providing the entity's name, ticker, RIC, LEI (Legal Entity Identifier) or other standard identifiers. 

Resource URL 

Format: https://api-eit.refinitiv.com/permid/search?q=<querystring>& access-token=<token> 

The Query Parameter 

There are two ways to specify a query’s search string:

• In the q parameter within the URL.

• In the Q HTTP header. 

You can either specify just the search string value, or prefix it with “<fieldname>:” in order to constrain the search to a specific field. For example: 

• Query parameter: q=tri This query returns any entity that contains the substring ”tri” in any of its fields (e.g. “ Thomson Reuters”, “Triton Development SA”, “Tri-Continental Corp”, “Patrick Smith”).

• Query parameter: q=ticker:TRI This query returns organizations, instruments and quotes with an exact match of “TRI” as their ticker value. (In this case, “Tri-Continental Corp” is filtered out of the results, as its ticker is “TY” and not “TRI”.) 

 

API Request 

HTTP verb: GET. 

Request parameters: 

Parameter Description
access-token

The unique access token allocated to a registered user.  If passed, the response contains additional fields that are available only to registered users. Can be passed as: • The access-token URL parameter:  access-token=<token> 

• The x-ag-access-token HTTP header:  x-ag-access-token: <token> 
entitytype 

The type of entity to search for. Possible values are: 

• entitytype=all (the default)

• entitytype=organization

• entitytype=instrument

• entitytype=quote
format 

Format of the response. Possible values are: 

• format=JSON (the default) • format=XML 
num 

The maximum number of results returned for each entity (separately). Possible values are: 

• num=5 (the default)

• num=10

• num=20

• num=50

• num=100 
order 

 The order of the search results. Possible values are: 

• order=rel  – The default. Descending order of relevance, i.e. quality of string match.

• order=az – Ascending alphabetical order of the entity name.

• order=za – Descending alphabetical order of the entity name.
q

Mandatory. The query string.  Examples of search strings: 

• Search in all fields:

o Microsoft o MSFT.O

o 4295861160 •

Seach in specific field: 

o name:microsoft 

o ticker: msft 

o ric: MSFT.O

o permid: 4295861160

o lei:INR2EJN1ERAN0W5ZP974 
start  The index of the first result returned, in the list of results ordered according to the order parameter. The index is 1-based. For example, if start=7, num=10  and there are 100 available results, results 7 through 16 are returned. 

API Response 

The lookup response contains the following general parameters

Parameter Description  
result  The search results. This element’s format is determined by the format request parameter. Its fields depend on the entity type.   
status  Numeric  HTTP return code. (E.g. Success=200)   
total  The number of results returned.   
errorcode  A specific error code that is returned when status!=200.   
errordescription  A textual description of the error that occurred.