Method Name | Description |
---|---|
enroll | Enrolls a participant in a study on the server. The response includes a globally unique <application-token>; to be used in subsequent communication from the mobile app. Parameters: -- studyId (required) - A pre-existing study on the server. -- token (required) - Enrollment token string provided by the participant. Token validation is case-insensitive. The token is used only once for enrollment; previously enrolled tokens cannot be used again. -- allowDataSharing (required) - Whether the participant consents to sharing data with third parties. Valid values: "true", "false", "NA" Afterwards, all submissions to the server are done using the <application-token>. |
validateEnrollmentToken | Validates an enrollment token, but does not actually enroll the participant. When successful, returns a JSON object that includes the names and values of all pre-enrollment participant properties associated with that participant. Parameters: -- Same params as enroll above. |
resolveEnrollmentToken | Given a valid enrollment token, returns the studyId associated with the folder where the token was generated, whether or not that token has already been used for enrollment. Parameters: -- token (required) - Enrollment token provided by the participant. |
withdrawFromStudy | Un-enrolls a participant. Option to retain or delete data. Parameters: -- participantId (required) - The <application-token> provided upon enrollment success. -- delete - Optional boolean to delete the withdrawn participant's data. Defaults to FALSE. |
processResponse | Saves survey responses to the study. Parameters: -- No parameters in the URL string, but the JSON object provided in the POST body contains the <application-token>. |
http://localhost:8080/mobileappstudy-enroll.api?studyId=<study-id>&token=<enrollment-token>&allowDataSharing=NA
http://localhost:8080/mobileappstudy-validateEnrollmentToken.api?studyId=<study-id>&token=<enrollment-token>&allowDataSharing=NA
http://localhost:8080/mobileappstudy-withdrawFromStudy.api?participantId=<app-token>&delete=<boolean>
http://localhost:8080/mobileappstudy-processResponse.api? (The <app-token> is provided in the posted JSON body.)
{
"success" : true
"data" :
{
"appToken" : "<app-token>",
}
}
{
"success": true,
"data": {
"preEnrollmentParticipantProperties": [
{
"propertyId": "ExternalConsentStatus",
"value": "Fully Consented"
}, {
"propertyId": "Cohort",
"value": "Traditional Diet"
}
]
}
}
{
"exception" : "<message>",
"success" : false,
"errors" : [
{
"msg" : "<message>",
"field" : "form|studyId|token",
"id" : "form|studyId|token",
"message" : "<message>"
}
]
}
{
"success": false,
"exception": "InvalidToken",
"errors": [{
"message": "Invalid token supplied",
"field": "EnrollmentToken",
"id": "abcd1234"
}]
}
Message | Field | Cause |
---|---|---|
Invalid input format | form | The data provided in the API could not be deserialized properly. |
StudyId is required for enrollment | form | Empty or no studyId provided. |
Study with studyId "XXX" does not exist | studyId | Invalid studyId provided. |
Token already in use | form | The provided token already has a participant id associated with it in the study's container. |
Invalid token: "YYY" | token | The checksum for the token is incorrect. |
Unknown token: "ZZZ" | token | The token provided has a valid checksum but it is not associated with the given studyId. |
Token is not associated with a study ID | token | There is no study associated with the submitted token. |
Token is required | form | The study associated with the given studyId requires an enrollment token to be provided. |
Attribute | type/values | Description |
---|---|---|
propertyId | string | A unique identifier under study for participant property. |
propertyName | string | A user friendly name for participant property. eg: Date Of Appointment. |
propertyType | PreEnrollment/PostEnrollment | This defines what type of participant property it is. |
propertyDataType | string | The type of the property (string, boolean, etc) |
shouldRefresh | boolean | Whether to refresh participant property value periodically or not. |
dataSource | ExternalSystem/Other | Defines from where the value will be populated. |
status | active/deactivated | Status of participant property |
value | depends on type | value of participant property sent by external system |