Record Matching - API Parameters

The PermID Record Matching API allows you to match your own entity Person, Organization, Instrument, and Quote records with Refinitiv’ PermIDs. Once you have the PermID for a specific entity, you can retrieve the entity using its PermID URL and enrich your database with the full extent of Refinitiv data. The PermID Record Matching API is a REST API, which uses the POST verb. You can provide the entity records to match either as part of the REST call body, or in a CSV (Comma-Separated Values) file. See the following sections to learn how to format both types of requests. 

Note: When matching the Person entity, you can submit up to 400 records to resolve in one request, and up to 1000 records for other entities. 

 

Resource URLs

Match records in request body: https://api-eit.refinitiv.com/permid/match 

Match records in file: https://api-eit.refinitiv.com/permid/match/file 

 

API Request 

HTTP verb: POST 

Request parameters: 

Parameter Description
x-openmatch-dataType   Mandatory. The matched entity type (Values: Person, Organization, Instrument, Quote).
X-AG-Access-Token Mandatory. Your PermID access token.
Content-Type Mandatory. For the permid/match/file end point: multipart/form-data For the permid/match end point: text/plain
x-openmatchnumberOfMatchesPerRecord      Number of matches to output for each record
   

 

Input File Formatting 

When calling the Record Matching API, if you provide your entity records in a file, you must format it as a Comma-Separated Values (CSV) file. A CSV file is a plain-text format for rendering tablular data, and has the following properties: • Each line in the CSV file is a row of the table. • Field names or values are separated by commas. • Rows are separated by newline characters. • The first line is the header row, containing field names. • All subsequent lines are records, containing field values. For example, the following text is the contents of a CSV file containing Organization records. Note the field names in the first line, and that some field values are empty.

Note: You can download CSV template files for each entity type at https://permid.org/match 

API Response 

Among other information, the PermID servers replies 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 was handled successfully by the server.
  • The Response Body contains the actual data you requested. Here are the details:

The response is returned in JSON format. The following table describes the Response parameters

Parameter Description
outputContentResponse  A JSON section matching your input records to PermID URLs. See Match Fields in the Response for details. 
errorCode A numeric error code (only present if an error was encountered while processing the request). 
errorCodeMessage A textual description of the error.
headersIdentifiedSuccessfully   A list of the field headers in the input that are compliant with the input template and were successfully processed. 
headersNotIdentified  A list of the field headers in the input that are not compliant with the input template and therefore not used for matching. This allows you to debug your input template and name the fields correctly.
headersSupportedWereNotSent  A list of supported fields headers that were not used in the input CSV file. This allows you to verify that the field names you sent are correct, and informs you of additional fields you can use to improve matching. 
numReceivedRecords  The number of input records. 
numProcessedRecords The number of input records that were processed successfully. 
numErrorRecords The number of input records that were not processed due to an error.
Matched  The number of valid input records for which a match was found. 
Unmatched  The number of valid input records for which no match was found. 
requestTimeInMs The time in milliseconds that the request took to process
resolvingTimeInMs The time in milliseconds that was spent only on the matching logic
uploadedFileName The name of the input file (if there was one)

The Response Body contains a number of fields, amongst which the outputContentResponse field is a key one. This field is actually an array of matching records found for the identifiers you requested. Each matching record gives 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 matched PermID against your request. For example,  the Match OpenPermID field denotes the URL of the the matched PermID  (e.g: https://permid.org/1-4295903297), details of which can be viewed (as shown), by opening the URL in any standard web browser. 

The following table describes the fields returned for each matching entity. 

Parameter Description
ProcessingStatus  OK or Error. An error means the input record was invalid, and in this case the reason for the error is included in the ProcessingStatus value
Match OpenPermID The PermID of the matched entity. 
Match OrgName The matched organization, or the organization of the matched quote, instrument or person.
Match Score A value between 0 and 1. This score indicates the probability that the match is correct. You can use this value to determine which matches might need manual review.
Match Level Excellent / Good / Possible – a textual label indicating the quality of the match, provided for readability. (Excellent =>0.9, Good= > 0.6, Possible =>0.1). 
Match Ordinal The index of the matched entity. For example, if you requested up to 5 matches, you may receive response records numbered 1, 2, 3, 4 and 5. 
Original Row The row number of the original input record that produced this match. 
Match First Name For Person only. The first name of the matched person.
Match Last Name For Person only. The last name of the matched person. 
Match OrgOpenPermID For Person only. The PermID of the organization that the matched person belongs to.

 

References

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

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  Record Matching API or any support questions in general, please use the Q&A section of the Developer Community and raise them there.