Try out the Record Matching API using the Swagger UI

The goal of this tutorial 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 for trying out the Record Matching API

Instructions

1. Upload records as a csv file

Click on the 'Try it Out' button to enable the input parameter fields
Paste your access token (API key) into the access-token field (If you do not have a access token, click here to view instructions to generate one)
Upload your input data file, at appropriate
Click on 'Execute'

At this instance, the Swagger UI sends the request to the PermID server, await for the response and displays it

2. Upload records as plain text

Click on the 'Try it Out' button to enable the input parameter fields
Paste your access token (API key) into the access-token field (If you do not have a access token, click here to view instructions to generate one)
Enter text in the standard format in the Text field. The format is shown below:

LocalID,Standard Identifier,Name,Country,Street,City,PostalCode,State,Website

1,RIC:AAPL.O|Ticker:AAPL,Apple,US,"Apple Campus, 1 Infinite Loop",Cupertino,95014,California,

Click on 'Execute'

At this instance, the Swagger UI sends the request to the PermID server, await for the response and displays it

Among other information, the API response includes a Response Code and a Response Body

Response Code: 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 handled successfully by the server
Response Body: The Response Body contains the actual Matching results . For each entity sent for matching, the response contains at least 1 match record. If the input record was successfully matched, there are one or more matching PermID entities in the response, depending on the x-openmatch-numberOfMatchesPerRecord value supplied in the request, and the number of matches found. A sample response body is shown below:

    	
            Response Body for 'Upload records as a csv file'
{

"ignore": " ",

"uploadedFileName": "Organization_input_template_with_examples.csv",

"unMatched": 0,

"matched": {

"total": 9,

"excellent": 9

},

"numReceivedRecords": 9,

"numProcessedRecords": 9,

"numErrorRecords": 0,

"headersIdentifiedSuccessfully": [

"localid",

"standard identifier",

"name",

"country",

"street",

"city",

"postalcode",

"state",

"website"

],

"headersNotIdentified": [],

"headersSupportedWereNotSent": [],

"errorCode": 0,

"errorCodeMessage": "Success",

"resolvingTimeInMs": 4256,

"requestTimeInMs": 4256,

"outputContentResponse": [

{

"ProcessingStatus": "OK",

"Match OpenPermID": "https://permid.org/1-4295905573",

"Match OrgName": "Apple Inc",

"Match Score": "99%",

"Match Level": "Excellent",

"Match Ordinal": "1",

"Original Row Number": "2",

"Input_LocalID": "1",

"Input_Name": "Apple",

"Input_Country": "US",

"Input_Street": "Apple Campus, 1 Infinite Loop",

"Input_City": "Cupertino",

"Input_PostalCode": "95014",

"Input_State": "California"

},

{

"ProcessingStatus": "OK",

"Match OpenPermID": "https://permid.org/1-4295905573",

"Match OrgName": "Apple Inc",

"Match Score": "92%",

"Match Level": "Excellent",

"Match Ordinal": "1",

"Original Row Number": "3",

"Input_LocalID": "2",

"Input_Name": "Apple"

},

{

"ProcessingStatus": "OK",

"Match OpenPermID": "https://permid.org/1-4295875158",

"Match OrgName": "Teva Pharmaceutical Industries Ltd",

"Match Score": "99%",

"Match Level": "Excellent",

"Match Ordinal": "1",

"Original Row Number": "4",

"Input_LocalID": "3",

"Input_Name": "Teva Pharmaceutical Industries Ltd",

"Input_Country": "IL",

"Input_City": "Petah Tikva"

},

{

"ProcessingStatus": "OK",

"Match OpenPermID": "https://permid.org/1-4297589397",

"Match OrgName": "Tata Sky Ltd",

"Match Score": "92%",

"Match Level": "Excellent",

"Match Ordinal": "1",

"Original Row Number": "5",

"Input_LocalID": "4",

"Input_Name": "Tata Sky",

"Input_Country": "IN"

},

{

"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": "6",

"Input_LocalID": "5",

"Input_Standard Identifier": "RIC:IBM.N|Ticker:IBM"

},

{

"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": "7",

"Input_LocalID": "6",

"Input_Standard Identifier": "Ticker:MSFT"

},

{

"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": "8",

"Input_LocalID": "7",

"Input_Standard Identifier": "LEI:INR2EJN1ERAN0W5ZP974"

},

{

"ProcessingStatus": "OK",

"Match OpenPermID": "https://permid.org/1-4297297477",

"Match OrgName": "Facebook Inc",

"Match Score": "100%",

"Match Level": "Excellent",

"Match Ordinal": "1",

"Original Row Number": "9",

"Input_LocalID": "8",

"Input_Standard Identifier": "Ticker:FB&&Exchange:NSM"

},

{

"ProcessingStatus": "OK",

"Match OpenPermID": "https://permid.org/1-4295905573",

"Match OrgName": "Apple Inc",

"Match Score": "100%",

"Match Level": "Excellent",

"Match Ordinal": "1",

"Original Row Number": "10",

"Input_LocalID": "9",

"Input_Standard Identifier": "Ticker:AAPL&&MIC:XNGS"

}

]

}
 
Response Body for 'Upload records as plain text'
{

  "ignore": "    ",

  "unMatched": 0,

  "matched": {

    "total": 1,

    "excellent": 1

  },

  "numReceivedRecords": 1,

  "numProcessedRecords": 1,

  "numErrorRecords": 0,

  "headersIdentifiedSuccessfully": [

    "localid",

    "standard identifier",

    "name",

    "country",

    "street",

    "city",

    "postalcode",

    "state",

    "website"

  ],

  "headersNotIdentified": [],

  "headersSupportedWereNotSent": [],

  "errorCode": 0,

  "errorCodeMessage": "Success",

  "resolvingTimeInMs": 154,

  "requestTimeInMs": 154,

  "outputContentResponse": [

    {

      "ProcessingStatus": "OK",

      "Match OpenPermID": "https://permid.org/1-4295905573",

      "Match OrgName": "Apple Inc",

      "Match Score": "100%",

      "Match Level": "Excellent",

      "Match Ordinal": "1",

      "Original Row Number": "2",

      "Input_LocalID": "1",

      "Input_Standard Identifier": "RIC:AAPL.O|Ticker:AAPL",

      "Input_Name": "Apple",

      "Input_Country": "US",

      "Input_Street": "Apple Campus, 1 Infinite Loop",

      "Input_City": "Cupertino",

      "Input_PostalCode": "95014",

      "Input_State": "California"

    }

  ]

}

References

To learn more and for a detailed description of the API response, please refer the Record Matching API

We also recommend you to follow the Record Matching Tutorials that explains how to leverage the API in Java example applications

Questions?

If you have any querstions regarding the use of Entity Search API or any support questions in general, please use the Q&A section of the Developer Community and raise them there.