PermID - Entity Search · RESTful API

API Family: Open PermID

Entity Search - Lookup Tutorial

Download tutorial source code

Click here to download

Last update August 2016
Environment Windows, Linux
Compilers JDK 1.7 or greater
Prerequisites Components
  • Java compiler, optional IDE, requesting access token
  • Apache HTTP client (tested with http-components-client 4.4)
  • Java-json is optional


The PermID Service lets you utilize the permanent ID of about 5.96mn organizations, 300K equity instruments, and 1.72mn equity quotes (coverage as of May 2020), from the Refinitiv core entity data set. PermID Service provides access to Refinitiv permanent identifiers (permanent unique IDs formatted as Uniform Resource Identifiers) along with the associated descriptive fields that Refinitiv exposes to the public. The descriptive fields enable the user to verify that a consumed permID represents the entity of interest.

The data is live; records are updated every 15 minutes.

The goal of this tutorial is to retrieve an entity info by passing its permid to Entity Search Lookup access point


The Entity-Search API enables users to retrieve entities in two ways:

  1. By including in the request the PermID service itself.
  2. By searching for an entity by name, ticker, RIC (Reuters Instrument Code).

This tutorial goes over the first way, and it illustrates the implementation in Java. 

Please note that any language that supports HTTP can be used to implement.

Setup Steps

The steps include:

  • Get your access-token from the Try it Out! tab (read the Quick Start guide learn how to do it)
  • Review the example source code
  • Build and run
    • Setup Eclipse or other Java project
    • Or build the java example from the command line
    • Include HTTP client prerequisite libraries provided with the tutorial

Review the example code

The steps include:

  • Set URL; access point to connect to
    // set URL to connect to      
    String url = "";
  • Set PERMID that we wish to look up (ThomsonReuters)
    url = url.concat("/1-4295861160");
  • Set format
    // set format
    url = url.concat("?format=turtle");   
  • Add unique access token into query
  • // add unique access token 
    url = url.concat("&access-token="+args[0]);      
  • Create HTTP GET request
    String url = "";
    // create HTTP GET
    CloseableHttpClient client = HttpClientBuilder.create().build();
    HttpGet request = new HttpGet(url);      
  • Issue request
    // issue request
    HttpResponse response = client.execute(request);
  • Process response (output)
    // process response
    BufferedReader rd = new BufferedReader(new InputStreamReader(response.getEntity().getContent()));
    StringBuffer result = new StringBuffer();
    String line = "";
    while ((line = rd.readLine()) != null) {
    }// issue request

As an alternative to simple printing, for pretty-printing turtle response one can use Apache Jena:

Build and run

The quickest way to build and run is with an IDE, Eclipse or NetBeans would work great

To build and run from the command line:

  • Build:
    javac -cp ".;prereqs\httpclient-4.4.jar;prereqs\httpcore-4.4.jar" tr/test/*.java
  • Run
    java -cp ".;prereqs\httpclient-4.4.jar;prereqs\httpcore-4.4.jar;prereqs\commons-logging-1.2.jar"
              tr.test.HTTPClientEntitySearchGet YOURTOKENGOESHERE

Understanding the input

The request constructed by our example will look like this:

Request URL

From lookup service, we are requesting the information for permid 1-4295861160 which is Thomson Reuters Corp

Understanding the expected output​

The response will contain the information below, the raw output:

Response Code : 200
Results received: @prefix tr-common: <>
.@prefix CorporateControl: <>
.@prefix tr-fin: <>
.@prefix fibo-be-oac-cpty: <>
.@prefix mdaas: <>
.@prefix fibo-be-le-fbo: <>
.@prefix xsd:   <>
.@prefix tr-org: <>
.@prefix fibo-be-le-cb: <>
.@prefix vcard: <> .<>        a                            tr-org:Organization ;
        mdaas:HeadquartersAddress    "3 Times Sq\nNEW YORK\nNEW YORK\n10036-6564\nUnited States\n"^^xsd:string ;
        mdaas:RegisteredAddress      "Suite 400\n333 Bay Street\nTORONTO\nONTARIO\nM5H 2R2\nCanada\n"^^xsd:string ;
        tr-fin:hasOrganizationPrimaryQuote                <> ;
        tr-fin:hasPrimaryInstrument  <> ;
        tr-org:hasActivityStatus     tr-org:statusActive ;
        tr-org:hasHeadquartersPhoneNumber                "16462234000"^^xsd:string ;
        tr-org:hasHoldingClassification                tr-org:publiclyHeld ;
        tr-org:hasIPODate            "2002-06-12T04:00:00Z"^^xsd:dateTime ;
        tr-org:hasOrganizationFoundedDate                "1977-12-28T00:00:00Z"^^xsd:dateTime ;
        tr-org:hasRegisteredPhoneNumber                "14163608700"^^xsd:string ;
        tr-org:isIncorporatedIn      <> ;
        fibo-be-le-cb:isDomiciledIn  <> ;
        vcard:hasURL                 <> ;
        vcard:organization-name      "Thomson Reuters Corp"^^xsd:string .

The output format that we see is Turtle: Terse RDF Triple Language. For more information on Turtle please refer to:

And the meaning of this response, once parsed, is:


Learn more

For more information, developer guides, FAQ and Release Notes check out the documentation