17.4 Retrieve Participant Contact Information

Participant contact information comprises any participant contact details captured in the reserved fields within the study as well as the participant access code generated for accessing OpenClinica Participate.

The following endpoint is used to retrieve participant contact information. This may be helpful, for example, if you want to generate a mailing list of all participants, or integrating with a CTMS system, which may utilize this information.

Only users with site-level CRC and Investigator roles (or derivatives thereof) can call this endpoint to retrieve participant contact information. Removed participants are not included in the results.

Retrieving contact information is a two step process:

  1. An authorized user submits the request for retrieving participant information
  2. Once the job completes, the same user calls the download file endpoint to get the file containing extracted participant information

Below are the details about the two endpoints:

Submit the request:

GET {serverName}/pages/auth/api/clinicaldata/studies/{studyOID}/sites/{siteOID}/participants/extractParticipantsInfo

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

Request Parameters:

register: (Optional)

  • Possible values y or n. (Default is n)

When the value y is passed, participant contact information includes the Participant's access code for OpenClinica Participate application as well as the Status of the participant on Participate application. However, when register is passed as n then the access code and participate status is excluded.

Sample cURL request:

curl -X GET \
  {{serverName}}/pages/auth/api/clinicaldata/studies/{{studyOID}}/sites/{{siteOID}}/participants/extractPartcipantsInfo?register=y \
  -H 'Authorization: bearer {{authentication token}}'

Response Body on Success:

The endpoint submits the job in the background and returns a unique job UUID. This job UUID can be used to download the file which contains the retrieved participant information. Alternatively, the information can be accessed via the OpenClinica UI via Tasks > Bulk Actions Log.

job uuid: hi12345j-2b02-482f-3h7s-286d54555f25

Response Body on Operation Failure:

{
  "message": "errorCode.studyNotExist",
  "params": {
    "siteOid": "sdgsg",
    "studyOid": "sdgsd"
  }
}

Here are the possible error codes with their descriptions:

  • 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.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: The study does not have an enabled Participate module. 

Download the file:

GET {serverName}/pages/auth/api/jobs/{jobUuid}/downloadFile

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

Sample cURL request:

curl -X GET \
{{serverName}}/pages/auth/api/jobs/{{jobUuid}}/downloadFile \
  -H 'Authorization: bearer {{authentication token}}'

Here are the possible error codes with their descriptions:

  • errorCode.invalidUuid: The Job UUID specified in the request is not found.

Functional approval by rbhatnagar. Signed on 2019-08-02 5:09PM

Approved for publication by Benjamin Baumann (bbaumann), Principal. Signed on 2019-08-02 5:53PM

Not valid unless obtained from the OpenClinica document management system on the day of use.