Open PermID - Record Matching - RESTful API

API Family: Open PermID

Record Matching - Quick Start Guide

Introduction

The goal of this Quick Start is to guide you through the Record Matching REST API using it's dedicated Swagger User Interface. Swagger UI is a great tool that documents and allows you to test REST APIs. This guide shows you how to use it along with the Record Matching REST API. Once you have completed this QuickStart, you'll be able to experiment and then better understand the different operations, parameters of the API as well as the server responses. 

This Quick Start will guide you through the following steps: 

Get your access-token

The Open PermID Record Matching API requires an access-token to be provided for every API operation you call. This access-token (also known as an API Key) is unique and associated to your Open PermID account. The same token can be used for all Open PermID APIs (Record Matching, Entity Search and Calais Tagging). If you already have an Open PermID account, you can skip the following section and directly jump to the Display and copy your access-token section.

Create your Open PermID account and the associated access-token

Before you call any of the Open PermID operations you must register yourself on the Open PermID portal. The registering process creates both the Open PermID account and the associated access-token you need to call the API operations. 

To register to Open PermID, please follow the steps below: 

  1. In this page click on the Dev Tools tab
  2. Click on the Request A Key button
  3. Fill in the registration form with the required information and click on the Register button

Note: The above instructions explain how to register and create your Open PermID account via the Dev Portal. Alternatively, you can directly register via the Open PermID portal. To this aim, open the permid.org home page, click on Register at the top right of the page and follow the instructions.

Display and copy your access-token

Once your Open PermID account is created, you have access to the associated access-token. As you will need this token in the next section for calling API operations on the server, it may be a good idea to copy it to the clipboard. Then, you'll just have to paste it into the appropriate parameter of the request. Please execute the following steps to copy the token:

  1. In this page click on the Dev Tools tab.
  2. Click on My API keys
    Your Open PermID access-token is displayed as shown below

    The access-token is displayed after the Your Key: label. As you can see, this token is related to the BOLD-REGISTERED-PRODUCT that is the Open PermID product name.
    Note: In the context of the Open PermID APIs, the “access-token” and “API key” terms have the same meaning. However, even if these terms are synonyms, Open PermID users tend to use “Access token” or simply “Token” more frequently than “API key”.
  3. Click on Copy Key to copy the access-token in the clipboard.

Note: The above instructions explain how to get your access-token from the Dev Portal. Alternatively, you can get it from the Open PermID portal. To this aim, go to the permid.org home page, log in, at the top right of the page move the mouse over you email address and click on "Display my Token".

Call an API operation using the Swagger UI

Now that the access-token is in the clipboard, you are ready to call your first API operation. To this aim you'll use the Record Matching Swagger UI available under the Dev. Tools tab. This Swagger UI gives you access to the two POST operations of the Record Matching API (/match/file and /match). The following instructions explain how to use the /match POST operation to resolve the MSFT.O and IBM.N Reuters Instrument Codes (RIC).

  1. In the Dev Tools tab, click on the Swagger menu item to open the Record Matching Swagger UI
  2. Click on the /match POST operation to expand it and display the related parameters.
  3. Paste your access-token (aka. API key) into the x-ag-access-token field.
  4. Leave the x-openmatch-numberOfMatchesPerRecord parameter to 1.
  5. Leave the x-openmatch-dataType parameter to "Organization".
  6. Leave the Content-Type parameter to “text/plain”.
  7. Change the Text parameter to the following:
LocalID,Standard Identifier
1,RIC:MSFT.O
2,RIC:IBM.N
  1. Click on the Try it out! button.

After you clicked on Try it out!, the Swagger UI sends the request to the Open PermID server, waits for the response and displays it.

This is the kind of response you should get:

Check the server response

Among other information, the Open PermID server replied with a Response Code and a Response Body

  • The Response Code gives you a status on the request you sent. If everything went fine the returned code should be "200", meaning the request has been treated successfully by the server.
  • The Response Body contains the actual data you requested. Here are the details:
{
  "ignore": "     ",
  "unMatched": 0,
  "matched": {
    "total": 2,
    "excellent": 2
  },
  "numReceivedRecords": 2,
  "numProcessedRecords": 2,
  "numErrorRecords": 0,
  "headersIdentifiedSuccessfully": [
    "localid",
    "standard identifier"
  ],
  "headersNotIdentified": [],
  "headersSupportedWereNotSent": [
    "name",
    "street",
    "city",
    "postalcode",
    "state",
    "country",
    "website"
  ],
  "errorCode": 0,
  "errorCodeMessage": "Success",
  "resolvingTimeInMs": 36,
  "requestTimeInMs": 36,
  "outputContentResponse": [
    {
      "ProcessingStatus": "OK",
      "Match OpenPermID": "https://permid.org/1-4295907168",
      "Match OrgName": "Microsoft Corp",
      "Match Score": "100%",
      "Match Level": "Excellent",
      "Match Ordinal": "1",
      "Original Row Number": "2",
      "Input_LocalID": "1",
      "Input_Standard Identifier": "RIC:MSFT.O"
    },
    {
      "ProcessingStatus": "OK",
      "Match OpenPermID": "https://permid.org/1-4295904307",
      "Match OrgName": "International Business Machines Corp",
      "Match Score": "100%",
      "Match Level": "Excellent",
      "Match Ordinal": "1",
      "Original Row Number": "3",
      "Input_LocalID": "2",
      "Input_Standard Identifier": "RIC:IBM.N"
    }
  ]
}

This Response Body contains many fields that are out of the scope of this Quick Start guide. Please refer to the Record Matching User Guide to learn more about them. However, it’s worth mentioning that the interresting part of the response is contained in the outputContentResponse field. This field is actually an array of matching records found for the identifiers you requested. In the request you asked for two RICs (MSFT.O and IBM.N), the server replied with an outputContentResponse that contains two matching records: one for Microsoft and one for IBM. Each matching record gives you an indication on how close the matching is (see Match score and Match Level fields). More importantly, the Match OpenPermID field gives you the URL of the matching PermID. In your case the matching Open PermIDs are https://permid.org/1-4295907168 for Microsoft and https://permid.org/1-4295904307 for IBM.

Details of these Open PermIDs can be displayed by opening these URLs in your usual browser. Here is an example for Microsoft:

Troubleshooting

In the event things didn't go as expected, ensure you didn't make one of the following common mistakes:

The Dev. Tools tab has no Request a Key menu item and no My API keys menu item.
You are probably not logged in the Dev Portal. Please login or register if you do not have an account yet. 

My API keys displays "Looks like you have no apps" under the Apps & Keys title.
You probably didn’t create your Open PermID account and the associated access-token (aka. API key). Please follow the Create your Open PermID account and the associated access-token steps of this guide.

The Response Body has no content and the Response Headers displays the “no response from the server” error.
The access-token you used for the x-ag-access-token parameter may not be correct. Please verify you're using the right token.

To learn more

Now that you know how to use the Record Matching Swagger UI, we recommend you to spend some time experimenting the different operations and parameters of the API. 
We also recommend you to follow the Record Matching tutorial that explains how to leverage the API in a Java example application.

References

For more information, refer to the Record Matching User Guide.