Use this endpoint to add a new Participant to a study site, update an existing Participant’s contact information, or register a Participant for access to the OpenClinica Participate dashboard.

What You Can Do

You can use this endpoint to:

  • Add a Participant to a specific site.
  • Update Participant contact details such as first name, last name, email address, phone number, or Secondary ID.
  • Register a Participant to access the OpenClinica Participate dashboard.

Important Rules and Limitations

⚠️ Warning: The OpenClinica Participate module must be active for the study to register Participants.

ℹ️ Note:

  • Study-level Participants cannot be registered for Participate or have contact data entered.
  • CRCs and Investigators cannot see study-level Participants. Best practice is to always add Participants at the site level.
  • Site-level Participants cannot be reassigned to the study level (only reassignment to another site is supported).
  • This endpoint supports studies with Participant ID Method set to Manual Entry or System-generated.

Access Control

Authorized Roles

The following roles can call this endpoint:

  • Data Manager
  • Clinical Research Coordinator (CRC)
  • Investigator
  • Data Entry Person
  • Data Specialist

Site-level users can perform this action only for Participants at their own site.

Unauthorized Roles

The following roles cannot call this endpoint:

  • Monitors (study-level and site-level)
  • Viewers (study-level and site-level)

API Endpoints

Use one of the following POST endpoints:

Site-level

POST {customerName}/pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/participants (Site-level)

Study-level

POST {customerName}/pages/auth/api/clinicaldata/studies/{studyOID}/participants (Study-level)

Where {customerName} is your OpenClinica 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_OHI0%28TEST%29/participants?register=y' \
-H 'Authorization: Bearer {{authentication token}}' \
-H 'Content-Type: application/json' \
-d '{
"subjectKey": "OHIO-5",
"firstName": "OHIO-5",
"lastName": "ОНІО",
"emailAddress": "OHIOS@openclinica.com",
"phoneNumber": "+1 1234567890"
}'

Participant Contact Fields

You can include the following optional fields when creating or updating a Participant:

  • firstName
  • lastName
  • middleName
  • emailAddress
  • phoneNumber
  • secondaryId (also referred to as identifier)
  • streetAddress1
  • streetAddress2
  • country
  • city
  • state
  • postalCode
  • fullDob
  • hospitalNumber

ℹ️ Note:If secondaryId (identifier) is included, the Participant’s Secondary ID is updated.
If it is not provided, the existing Secondary ID remains unchanged.

Request Parameters

register (Optional)
Specifies whether to register the Participant for OpenClinica Participate.

  • Possible values: y or n
  • Default: n

Field Validation Rules

When you add or update Participant contact fields, strict validation rules are enforced. If any rule is violated, the API returns an error and rejects the request.

Name Fields

  • firstName: Maximum length of 35 characters
  • lastName: Maximum length of 35 characters
  • middleName: Maximum length of 35 characters

Address Fields

  • streetAddress1: Maximum length of 155 characters
  • streetAddress2: Maximum length of 155 characters
  • city: Maximum length of 155 characters
  • state: Maximum length of 155 characters
  • country: Maximum length of 155 characters
  • postalCode: Maximum length of 35 characters

Contact and Identifier Fields

  • emailAddress: Maximum length of 255 characters and must be a valid email format
  • phoneNumber: Maximum length of 17 characters and must match the required phone number format
  • secondaryId: Maximum length of 35 characters
  • hospitalNumber: Maximum length of 35 characters

These constraints are strictly enforced when data is submitted via the API.

Response Body on Success:

Response Body on Failure:

Error Codes

If the request fails, the response includes one of the following error codes:

Study and Site Errors

  • errorCode.studyNotExist: The study OID specified in the request is not found.
  • errorCode.studyNotAvailable: The study OID specified in the request is not in ‘Available’ status.
  • errorCode.siteNotExist: The site OID specified in the request is not found.
  • errorCode.siteNotAvailable: The site OID specified in the request is not in ‘Available’ status.

Authorization Errors

  • 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.

Participate Errors

  • errorCode.participateNotEnabled: OpenClinica Participate module is not active for the given Study and therefore, the operation is NOT allowed.

Participant ID Errors

  • errorCode.participantIDContainsUnsupportedHTMLCharacter: The Participant ID contains unsupported HTML (<, >) characters.
  • errorCode.participantIDLongerThan30Characters: The Participant ID exceeds the 30 character limit.
  • errorCode.participantsEnrollmentCapReached: The pre-set Participant enrollment limit has reached. No new participants can be added to this study.

Field Validation Errors

  • errorCode.invalidPhoneNumber: The phone number does not conform to the required format.
  • errorCode.invalidEmailAddress: The email address does not conform to the required format.
  • errorCode.emailAddressTooLong: The email address exceeds the 255 character limit.
  • errorCode.firstNameTooLong: The first name exceeds the 35 character limit.
  • errorCode.lastNameTooLong: The last name exceeds the 35 character limit.
  • errorCode.middleNameTooLong: The middle name exceeds the 35 character limit.
  • errorCode.streetAddress1TooLong: Street Address 1 exceeds the 155 character limit.
  • errorCode.streetAddress2TooLong: Street Address 2 exceeds the 155 character limit.
  • errorCode.cityTooLong: The city exceeds the 155 character limit.
  • errorCode.stateTooLong: The state exceeds the 155 character limit.
  • errorCode.countryTooLong: The country exceeds the 155 character limit.
  • errorCode.postalCodeTooLong: The postal code exceeds the 35 character limit.
  • errorCode.secondaryIdTooLong: The secondary ID exceeds the 35 character limit.
  • errorCode.hospitalNumberTooLong: The hospital number exceeds the 35 character limit.
  • errorCode.phoneNumberTooLong: The phone number exceeds the 17 character limit.