openspecimen/rest/ng/participants/match
Use this API to search the database that match one or more of the matching field.
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. By default, the value of this flag is false. |
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",
"cprId": 17018
}
/* 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. |