Record Matching - API Parameters
The PermID Record Matching API allows you to match your own entity Person, Organization, Instrument, and Quote records with LSEG 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 LSEG 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.