Participants/Bulk (Add and Update Bulk List of Participants)

16.4 participants/bulk (Add Bulk list of Participant IDs)

The participants/bulk endpoint is used to add a list of participant IDs to the Study/Site. Users can add the bulk list of participant IDs either at Study level or at the Site level.

Add bulk list of Participant IDs at the Study level
Add bulk list of Participant IDsat the Site level

The user must be authenticated prior to calling this service. The operation is allowed based on the user’s privileges.

At the Study level:

POST {serverName}/pages/auth/api/clinicaldata/studies/{studyOID}/participants/bulk

where {serverName} is your study URL. For example: https: //studyxyz.eu.openclinica.io/OpenClinica

At the Site level:

POST {serverName}/pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/participants/bulk

where {serverName} is your study URL. For example: https: //studyxyz.eu.openclinica.io/OpenClinica

Request Parameters:

Content-Type: text/xml
filename=”participantList.csv”

“participantList.csv” should be replaced with a CSV file that contains the list of participant IDs that need to be added to the study.

Here’s a sample CSV file for adding two participant IDs – JUNO-005 and JUNO-006

Response Body on Success:

{
"uploadCount":2,
"failureCount":0,
"message":SUCCESS",
"createdBy":"Bhatnagar Renuka",
"createdAt":"11-9-2018 12:09:22",
"failedParticipants":[],
"participants":[
	{	
		"subjectKey":"JUNO-005",
		"status":"Available"
	},
	{
		"subjectKey":"JUNO-006",
		"status":"Available"
	}]
}

Response Body on Operation Failure:

{
"uploadCount":0,
"failureCount":0,
"message":"errorCode.notSupportedFileFormat",
"createdBy":"Bhatnagar Renuka",
"createdAt":"11-9-2018 12:11:47",
"failedParticipants":[],
"participants":[]
}

Response Body on Operation Success but there are some failed to load participant IDs:

{
"uploadCount":1,
"failureCount":1,
"message":"SUCCESS",
"createdBy":"Bhatnagar Renuka",
"createdAt":"11-9-2018 12:11:47",
"failedParticipants":[
	{
		"subjectKey":"JUNO-006",
		"message":["errorCode.participantIDNotUnique"]
	}
],
"participants":[
	{
		"subjectKey":"JUNO-006",
		"status":"Available"
	}
]
}

If the operation fails or fails to add a particular participant ID, an appropriate errorCode is returned. The user should plan the follow-up action based on the returned errorCodes.

Below is the list of errorCodes with their descriptions:

Scenario: Bulk operation has failed:

errorCode.studyNotExist: The Study OID specified in the request is not found.
errorCode.siteNotExist: The Site OID specified in the request is not found.
errorCode.bulkUploadNotSupportSystemGeneratedSetting: Bulk particpant ID upload is not supproted when participant ID setting is set to System-generated. Change the settings to manual Participant ID and try again.
errorCode.notSupportedFileFormat: The file format is not supported. Only CSV files are accepted.
errorCode.noRoleSetUp: The user has no role assigned for the given Study/Site.
errorCode.noSufficientPrivileges: The user does not have sufficient privileges to perform this operation.

Scenario: Bulk operation is successful, but response has some failed Participants

errorCode.participantIDContainsUnsupportedHTMLCharacter: Participant ID contains unsupported HTML (<, >) characters.
errorCode.participantIDLongerThan30Characters: Participant ID exceeds 30 characters limit.
errorCode.participantIDNotUnique: Participant ID already exists.
errorCode.participantsEnrollmentCapReached: Participant Enrollment Limit has reached. No new participants can be added.

Export PDF