The bulk study event endpoint allows you to create or update study events for multiple Participant IDs at once. The functionality, constraints, and access control for this endpoint are the same as those for the single create and update study event endpoint.

You must be authenticated before calling this service. The operation is allowed based on your assigned privileges for the specified study and site.

Endpoint Details

URL:

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

Where:

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

Sample cURL Request

curl -X POST
 '{{serverName}}/pages/auth/api/clinicaldata/studies/S_JUNO%28PROD%29/sites/S_BOSTON_3152%28PROD/events/bulk' 
  -H 'Authorization: bearer {{authentication token}} 
  -H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' 
  -F 'file=@C:directoryfile.csv'

Request Parameters

This endpoint requires a CSV file that contains a list of Participant IDs and study event–related information. The CSV file must meet the following requirements.

Required Columns

  • ParticipantID
    • The file must include exactly one column with the header ParticipantID.
    • This column must contain the Participant ID.
  • StudyEventOID
    • The file must include a column for the Study Event OID.

Additional Columns by Action

Create a New Study Event

  • StudyEventRepeatKey must be empty.
  • StartDate must be present (time is optional).
  • EndDate is optional (time is optional).
  • StudyEventStatus is not used.

Update an Existing Study Event

  • StudyEventRepeatKey must be present and must be a valid integer.
    ℹ️ Note: When updating an existing event instance, set the EventRepeatKey to 2. This value indicates that the first occurrence of the event has already been completed.
  • StartDate is optional (time is optional).
  • EndDate is optional (time is optional).
  • StudyEventStatus is optional.
    ℹ️ Note: StudyEventStatus = Not Locked unlocks the event (sets Locked = No) without modifying the workflow status. Supported for both individual and bulk study event updates.

ℹ️ Note: File columns can appear in any order.

Column Value Restrictions

The following restrictions apply to values in the CSV file:

  • ParticipantID and StudyEventOID must be valid identifiers under the specified study and site.
  • StudyEventRepeatKey must be an integer.
  • StartDate and EndDate must use the format yyyy-MM-dd or yyyy-MM-dd hh:mm (if including time).
  • StudyEventStatus may include the following values:
    data entry started, stopped, skipped, locked, not locked, completed.

Sample CSV File

Here’s a sample CSV file for creating study event and modifying the study events for the given participants.

Response on Success

When the request is accepted, the endpoint submits the job to run in the background and returns a unique job UUID.

job uuid: ddbadff4-f015-4a2d-81e0-e3daf507bbfc

Response on Failure to Submit the Job

If the job cannot be submitted, the API returns an error response. Example:

{
  "message": "errorCode.siteNotExist",
  "params": {
    "siteOid": "S_OHIO(PRD)",
    "studyOid": "S_JUNO(PROD)"
  }
}

Submission-Level Error Codes

The following error codes may be returned if the job cannot be submitted:

  • errorCode.studyNotExist: The Study OID specified in the request was not found.
  • errorCode.siteNotExist: The Site OID specified in the request was not found.
  • errorCode.notSupportedFileFormat: The file format is not supported. Only CSV files are accepted.
  • errorCode.noRoleSetUp: You do not have a role assigned for the specified study or site.
  • errorCode.noSufficientPrivileges: You do not have sufficient privileges to perform this operation.

Job Processing and Logs

After the job completes, you can access the job’s log file in the OpenClinica user interface under Tasks and Bulk Actions Log.

If an error occurs while processing a specific record in the CSV file, an appropriate error code is returned for that record within the log file.

Record-Level Error Codes

The following error codes may appear in the job log for individual records:

  • errorCode.participantNotFound: No participant record was found for the specified Participant ID.
  • errorCode.missingParticipantID: The Participant ID value is missing.
  • errorCode.missingStudyEventOID: The Study Event OID value is missing.
  • errorCode.invalidStudyEventOID: The Study Event OID value is not valid.
  • errorCode.CommonEventCannotBeScheduled: The Study Event OID refers to a common event and cannot be scheduled.
  • errorCode.missingStartDate: The StartDate value is missing and the study event cannot be scheduled.
  • errorCode.invalidStartDate: The StartDate value is invalid.
  • errorCode.endDateBeforeStartDate: The EndDate occurs before the StartDate.
  • errorCode.invalidEndDate: The EndDate value is invalid.
  • errorCode.studyEventRepeatNotFound: The Study Event Repeat Key was not found for the specified participant.
  • errorCode.invalidEventStatus: The StudyEventStatus value is not valid.
  • errorCode.invalidEventTransitionStatus: The transition from the current study event status to the provided status is not allowed.