Get Matching Participants

openspecimen/rest/ng/participants/match

Use this API to search the database that match one or more of the matching field. Typically, you should use this API is before adding a new participant to check if the participant is already present in the database.

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.