Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Use this resource to register a new/existing participant in the OpenSpecimen application. Use HTTP POST method to call this API by passing the below details in JSON format.

...

Parameter
Details
participant

Details of the participant which is being registered. If the participant already exists then specify the identifier of that participant otherwise specify the complete details, below are the attributes of the participant:

ParameterDetails
idIdentifier of the participant being registered. Specify the identifier, if it already exists.
firstNameFirst name of the participant
middleNameMiddle name of the participant
lastNameLast name of the participant
uidUnique identifier of participant e.g Social Security Number
birthDatedate of birth of participant
vitalStatusVital status of the participant.
deathDatedate of death participant
gender

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 (Prior to v4.0)

ethnicities (From v4.0)

Patient's ethnicity statuses. permissible values are:

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

Note: Starting v4.0, ethnicity is a multi-value field in Participant.

sexGenotype

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}

pmiscollection 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


cpIdIdentifier of the protocol to which the participant is being registered.
cpTitleTitle of the protocol to which the participant is being registered.
cpShortTitleShortTitle of the protocol to which the participant is being registered.

ppid

[optional if autogeneration set at protocol level]

Protocol Participant Identifier, this is the identifier to uniquely identify the participant with in a protocol.

Note: If PPID is set to auto-generated at protocol level, then please leave this attribute blank.

registrationDateDate of the registration of participant
externalSubjectIdExternal subject id of the participant (optional)

Note: For the collection protocol attributes, any one is required from the three: cpId/cpTitle/cpShortTitle.

 


http[s]:<host>:<port>/openspecimen/rest/ng/collection-protocol-registrations/

...

Below is the example of the register participant:

 


URLopenspecimen/rest/ng/collection-protocol-registrations/
Request typeapplication/json
MethodPOST
json

{

   "participant":{

      "id":2

   },

   "cpId":1,

   "ppid":"ASCI123",

   "activityStatus":"Active",

   "registrationDate":"2014-04-21",

    "externalSubjectId": "TEST_001"

}

Response

{

   "id":5,

   "participant":{

      "id":2

   },

   "cpId":1,

   "ppid":"ASCI123",

   "activityStatus":"Active",

   "registrationDate":"1398105000000",

    "externalSubjectId": "TEST_001"

}

...


Error Cases :

code
Applies to
Status Message
200All resourcesParticipant registered successfully
400All requestsInvalid parameters, e.g  duplicate UID, duplicate PPID etc
401All requestsAuthorization failed, User doesn’t have Authority to register Participant for the given collection protocol
500All requestsInternal server error, Encountered server error while performing operations

...