openspecimen/rest/ng/participants/match
Use this API to find matching participants in the OpenSpecimen database. Use HTTP POST method to invoke this API by passing below details in JSON format. The API will attempt to find matching participants based on below input parameters.
Parameter | Details |
|---|---|
| lastName | Last name of the participant. Used in conjunction with birthDate. |
| uid | Country specific social security or national ID of the participant. For example, in US, this could be SSN. In India, this could be Aadhar number / PAN etc |
| birthDate | Participant's date of birth. Used in conjunction with lastName. |
| pmi | Participant's MRN and name of site that assigned the MRN. Refer below example for the field structure. |
| empi | Enterprise wide unique ID assigned to the participant. |
| reqRegInfo | Boolean specifying whether the registration details of matched participants needs to be populated in response. |
http[s]:<host>:<port>/openspecimen/rest/ng/participants/match
Use this URL to find matching participants in OpenSpecimen database.
Result:
The response of this matching request is either an empty array or list of matched participants.
Below is the example of the match participants request-response:
| URL | http[s]:<host>:<port>/openspecimen/rest/ng/participants/match |
| Method | POST |
| content-type | application/json |
| Method | POST |
| Body | {
"lastName" : "Dep",
"pmi" : {
"mrn" : "324r6",
"siteName" : "Lab2"
} ,
"uid" : "123-45-6789",
"reqRegInfo": true
}
|
Response | [
{
"matchedAttrs": ["pmi", "uid"]
"participant": {
"lastName" : "Dep",
"pmis" : [{
"mrn" : "324r6",
"siteName" : "Lab2"
}],
"uid" : "123-45-6789"
"id" : "1",
/** other participant attributes **/
/* registeredCps array is populated only if reqRegInfo = true in matching request */
"registeredCps": [
{
"cpShortTitle": "Lung Cancer",
"registrationDate": 1437282466892,
"ppid": "LC-007"
}
/* other registrations, if any */
]
}
]
|
Note:
matchedAttrs contains list of input attributes against which matching participant was found. The values could any of these ["empi" | "uid" | "pmi" | "lnameAndDob"]
Error Cases :
code | Applies to | Status Message |
|---|---|---|
| 200 | All resources | Matching request executed successfully |
| 400 | All requests | Invalid input parameters. Retrying request with correct parameter values might succeed. |
| 401 | All requests | Authorization failed. User doesn’t have rights to find matching participants. |
| 500 | All requests | Server error. Retrying request might not succeed. |