Page Comparison

openspecimen/rest/ng/participants/match

Use this resource to get matching participants in the OpenSpecimen application. Use HTTP POST method to call this API by passing the below details in JSON format. This will match against the below attributes only.

Below are the attributes which need to be sent in the request body:

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

Social security number of participant

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

of participantpmiscollection of Participant's medical record number used in their medical treatment.mrnParticipant's medical record number used in their medical treatment.siteNameName of the physical location.empiAny other unique identifier for patient, like enterprise master patient index number

...

. 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 add participant find matching participants in OpenSpecimen applicationdatabase.

Result:

The response of this request will contains the details of the created participantmatching request is either an empty array or list of matched participants.

Below is the example of the create participant:

match participants request-response:

URL	http[s]:<host>:<port>/openspecimen/rest/ng/participants/match
Method	POST
content-type	application/json
Method	POST
Body

json

Code Block
{


  "lastName" : "Dep",

"pmis" : [ {


  "pmi" :  {
    "mrn" : "324r6",


    "siteName" : "Lab2"

} ],


  } ,
  "uid" : "123-45-6789

"

",
  "reqRegInfo": true
}

Response

[

1]0:

{

Code Block
[ { "matchedAttrs": [

1] 0:

"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": [
        {
          "

,

"uid" : "123-45-6789"

}

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

Participant registered

Matching request executed successfully
400	All requests	Invalid

parameters, e.g duplicate SSN, duplicate MRN, invalid race etc

input parameters. Retrying request with correct parameter values might succeed.
401	All requests	Authorization failed

,

. User doesn’t have

privileges to register Participants

rights to find matching participants.
500	All requests

Internal server error, Encountered server error while performing operations

Server error. Retrying request might not succeed.

Versions Compared

Old Version 7

New Version Current

Key