The participants/bulk endpoint is used to perform the participants endpoint function on a list of participant IDs.

The functionality, stipulations and the access control all applies as per the participants endpoint. Click here to learn about the participants endpoint.

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

URL:

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

Sample cURL Request:

curl -X POST 
  {{serverName}}/pages/auth/api/clinicaldata/studies/S_JUO%28TEST%29/sites/S_BOSTON_7642%28TEST%29/participants/bulk?register=y 
  -H 'Authorization: bearer {{authentication token}} 
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' 
  -F 'file=@C:directoryfile.csv'

Request Parameters:

  • register: Possible values – y or n.
    • When set to n, then participants are NOT reigstered for OpenClinica Participate application
    • When set to y, then system generates an access code for each participant and register them for OpenClinica Participate application

This endpoint also requires a CSV file with list of participant IDs and their corresponding contact information. Below are the requirements for the CSV file content:

  • File must have ONE column with header as ‘ParticipantID’. This column must contain the Participant ID.
  • File can have either of the following columns: (They are all optional)
    • firstName
    • lastName
    • emailAddress
    • phoneNumber
    • identifier
  • File columns can be in any order.
  • Below are the restrictions on the values in these columns:
    • firstName and lastName — Must be less than or equal to 35 characters in length
    • emailAddress — Must be an email address and must be less than 255 characters in length
    • phoneNumber — Must be numeric and less than or equal to 15 digits in length.
    • identifier — Must be less than or euqal to 35 characters in length

“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:

job uuid: d2dbdc07-c0f9-4e4d-9ae2-81f5bfaed1c9

Response Body on Failure:

errorCode.invalidSiteIdentifier

Below is the list of errorCodes with their descriptions:

  • errorCode.studyNotExist: The Study OID specified in the request is not found.
  • errorCode.invalidSiteIdentifier: 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.
  • errorCode.participateInActive: Participate module is not active for the given study and register flag is set as y in the request.

Once the job has completed then the logfile can be accessed within the Study system under the user’s login at page: Tasks –> Bulk actions log

In case of in processing any particular record in the file, an appropriate errorCode will be returned for that record within the logfile. Below is the list of the errorCodes within their descriptions:

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