Access the participant endpoint on a list of participant IDs in bulk. The functionality, stipulations, and the access control all apply as per the participants endpoint.

Functionality:

  • Create/Update participants in bulk for a given site.
  • Update participant contact information like first name, last name, email address, or mobile number.
  • Register the participant to access OpenClinica Participate dashboard.

Stipulations:

  • Participants can be registered for OpenClinica Participate ONLY when the Participate module is Active for the given study.
  • This endpoint can be called either when the study has the Participant ID Method set to “Manual Entry” or “System-generated”

Access Control:

  • User roles authorized to call this endpoint and perform the specified operations:
    • Data Managers
    • Clinical Research Coordinators
    • Investigators
  • Site level roles can perform this operation only on their site’s participants.
  • User roles NOT authorized to call this endpoint:
    • Monitors (study level and site level)
    • Viewers (study level and site level)

Before calling the API, you will need to be authenticated and you will need to get access based on your user roles permissions.

Study-level participants can’t be created in bulk via API. (Participants will need to be assigned to a site).

URL:

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

where {customerName} is your customer URL. For example: https://customerxyz.openclinica.io/OpenClinica

Sample cURL Request:

curl -X POST 
  {{customerName}}/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, participants will NOT be registered for OpenClinica Participate Module
    • When set to y, the system generates an access code for each participant and registers them for OpenClinica Participate Module

This endpoint also requires a CSV file with list of participant IDs and their corresponding contact information, if desired.

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.
  • The following restrictions pertain to 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 in the format of +# ##
      • Starts with +
      • Up to 3 digits after + for the country code
      • A space after the country code
      • Up to 14 digits after space for the area code and local code
      • No other characters permitted
      • Up to 17 characters total
    • identifier — Must be less than or equal 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 Error Codes 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.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, you can access job’s log file in the OpenClinica UI via Tasks and Bulk Actions Log.

If the system encounters a problem processing any particular record in the file, an appropriate error code will be returned for that record and displayed within the log file.

Here are the Possible Error Codes and 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.
  • errorCode.firstNameTooLong: First name value supplied in the record exceeds 35 character limit.
  • errorCode.emailAddressTooLong: Email address value supplied in the record exceeds 255 character limit.
  • errorCode.mobileNumberTooLong: Mobile number value supplied in the record exceeds 17 character limit.
  • errorCode.invalidMobileNumber: Mobile number value supplied in the record not a valid mobile number.
  • errorCode.invalidEmailAddress: Email address value supplied in the record not a valid email address.