Page Comparison

openspecimen/rest/ng/participants/matchParticipantsmatch

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.

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

...

Parameter

...

Details

...

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

ssnSocial security number of participantbirthDatedate of birth of participantvitalStatusVital status of the participant.deathDatedate of death participantgender

gender of the participant, permissible values are

{Male Gender, Female Gender, Unknown, Unspecified}

race

Patient's racial origination, permissible values are:

{American Indian or Alaska Native, Asian, Black or African American, Native Hawaiian or other Pacific Islander, Not Reported, Unknown, White}

ethnicity

Patient's ethnicity status. permissible values are:

{Hispanic or Latino, Not Hispanic or Latino, Not Reported, Unknown}

Sex Genotype

The genetic constitution of the individual; the characterization of the genes. Permissible values are:

{XX Genotype, XY Genotype, XXX, Klinefelter’s Syndrome, XXXY syndrome, XXYY syndrome, Mosaic including XXXXY, Penta X syndrome}

pmiCollectioncollection 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.

. 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/matchParticipantsmatch

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 participantmatch participants request-response:

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

json

Body

Code Block
{

"ethnicity" : "Unknown",

"firstName" : "Jhon",

"gender" : "Male Gender",

"lastName" :


  "lastName" : "Dep",

"pmiCollection" : [ {


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


    "siteName" : "Lab2"

} ],

"race" : [ "Asian" ],

"ssn" :


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

,
  "reqRegInfo": true
}

Response

Code Block
[

1]0:

{

"ethnicity" : "Unknown",

"firstName" : "Jhon",

"gender" : "Male Gender",

"lastName" : "Dep",

"pmiCollection" : [ { "mrn" : "324r6",

"siteName" : "Lab2"

} ],

"race" : [ "Asian" ],

"id" : "1",

"ssn" : "123-45-6789"

}

...


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

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 3

New Version Current

Key