User Registration Server API

2024-04-19

This topic is under construction.

User/Registration Services

User/Registration Services provide mechanisms to register users, manage their profiles, settings, preferences, activity and progress in the app.

Learn about Phase 2A Changes to this API in this topic: Mobile Client API.

Headers for User/Registration Services

Request header for all user/registration requests (auth and userId is not required for login/registration/forgot password)

HeaderParams	Values
auth	string; authentication token
userId	string
orgId	string
applicationId	string

Response header for all user/registration requests

HeaderParams	Values
status	http status code
StatusMessage	string

RegisterUser

Request:

Method	URL
POST	/register

Params	Values
emaiId	string
password	string

Response:

Params	Values
message	string
userId	string
verified	bool
auth	string
refreshToken	string

ConfirmRegistration

Confirm user registration.

Request:

Method	URL
POST	/verify

Params	Values
emailId	string
code	string

Response:

Params	Values
message	string

ResendConfirmation

Resend confirmation email.

Request:

Method	URL
POST	/resendConfirmation

Params	Values
emailId	string

Response:

Params	Values
message	string

LoginUser

Request:

Method	URL
POST	/login

Params	Values
emailId	string
password	string

Response:

Params	Values
message	string
userId	string
verified	bool
auth	string
refreshToken	string
resetPassword	bool; true if login with temporary password

LogoutUser

Logout user.

Request:

Method	URL
DELETE	/logout

Params	Values
reason	string; user_action/error/security(jailbroken/rooted)

Response:

Params	Values
message	string

ForgotPassword

Request to reset password.

Request:

Method	URL
POST	/forgotPassword

Params	Values
emailId	string

Response:

Params	Values
message	string

ChangePassword

Request to change password.

Request:

Method	URL
POST	/changePassword

Params	Values
currentPassword	string
newPassword	string

Response:

Params	Values
message	string

GetUserProfile

Fetch saved user profile from the server.

Request:

Method	URL
GET	/userProfile

Response:

Params	Values
message	string
profile	{ "emailId": string }
settings	{ "remoteNotifications": bool, "localNotifications" :bool, "touchId" :bool, "passcode" :bool, "locale" :string, "reminderLeadTime": string }

UpdateUserProfile

Update user profile on server.

Request:

Method	URL
POST	/updateUserProfile

Params	Values
settings	{ "remoteNotifications": bool, "localNotifications": bool, "touchId": bool, "passcode": bool, "reminderLeadTime" :string, "locale": string }
info	{ "os": string, android/ios "appVersion": string, "deviceToken": string }
participantInfo	{ "studyId": string, "participantId": string, "enrolledDate": string }

Params

Values

settings

{
  "remoteNotifications": bool,
  "localNotifications": bool,
  "touchId": bool,
  "passcode": bool,
  "reminderLeadTime" :string,
  "locale": string
}

info

{
  "os": string, android/ios
  "appVersion": string,
  "deviceToken": string
}

participantInfo

{
  "studyId": string,
  "participantId": string,
  "enrolledDate": string
}

Response:

Params	Values
message	string

GetStudyState

Fetch studies state

Request:

Method	URL
GET	/studyState

Response:

Params	Values
message	string
studies	[ { "studyId": string, "status": string, "enrolledDate": string, "participantId": string, "bookmarked": bool, "completion": integer, "adherence": integer, } ]

UpdateStudyState

Update study state

Request:

Method	URL
POST	/updateStudyState

Params	Values
studies	[ { "studyId": string, "status": string, "enrolledDate": string, "participantId": string, "bookmarked": bool, "completion": integer, "adherence": integer } ]

Response:

Params	Values
message	string

UpdateEligibilityConsentStatus

Update eligibility and consent status.

Request:

Method	URL
POST	/updateEligibilityConsentStatus

Params	Values
studyId	string;
eligbibility	bool; eligible/not eligible
consent	{ "version": string, consent version "status": string, completed/pending "pdf": string base-64 encoded string }
sharing	string;

Response:

Params	Values
message	string

GetConsentDocument

Download consent PDF from server by passing studyId and consent version. If no consent version is provided, latest version of consent should be returned.

LabKey will also use this service, in that case, user id in header params should be treated as app token/participant id.

Request:

Method	URL
GET	/consentDocument

Params	Values
studyId	string
consentVersion	string

Response:

Params	Values
message	string
consent	{ "version":string, consent version "type": string, application/pdf "content": string base-64 encoded string }
sharing	string;

UpdateActivityState

Update activity state.

Request:

Method	URL
POST	/updateActivityState

Params

Values

studyId

string; study identifier

activity

[
  {
    "activityId": string,  activity identifier
    "activityVersion": string, activity version
    "activityRunId": string, activity run identifier
    "activityState": string, activity state
    "bookmarked": bool,
    "activityStartDate": string,
    "activityEndDate": string,
    "anchorDateVersion": string,
    "anchorDatecreatedDate": "string",
    "lastModifiedDate": string,
    "customScheduleRuns": [{
        "runStartDate": string,
	"runEndDate": string
    }],
    "activityRun": {
        "total" :integer,
        "completed" :integer,
        "missed" :integer
    }
  }
]

Response:

Params	Values
message	string

GetActivityState

Fetch activity state.

Request:

Method	URL
GET	/activityState

Params	Values
studyId	string; study identifier

Response:

Params

Values

message

string

activities

[
  {
    "activityId": string,
    "activityVersion": string,
    "activityRunId": string,
    "activityState": string,  activity state
    "bookmarked": bool,
    "activityStartDate": string,
    "activityEndDate": string,
    "anchorDateVersion": string,
    "lastModifiedDate": string,
    "anchorDatecreatedDate": string,
    "customScheduleRuns": [{
	"runStartDate": string,
	"runEndDate": string
    }],
    "activityRun": {
        "total":integer,
        "completed":integer,
        "missed":integer
    }
  }
]

WithdrawFromStudy

Delete user’s study info from server.

Request:

Method	URL
DELETE	/withdraw

Params	Values
studyId	string; study id
deleteData	bool: should delete study data

Response:

Params	Values
message	string

Deactivate Account

Request:

Method	URL
DELETE	/deactivate

Params	Values
deleteData	string array(array of studyIds)

Response:

Params	Values
message	string

Feedback

Provide feedback about the app.

Request:

Method	URL
POST	/feedback

Params	Values
subject	string
body	string

Response:

Params	Values
message	string

ContactUs

Reach out to app owner

Request:

Method	URL
POST	/contactUs

Params	Values
subject	string
body	string
firstName	string
email	string

Response:

Params	Values
message	string

Refresh Token

Get new accesstoken and refreshtoken.

Request:

Method	URL
POST	/refreshToken

Params	Values
refreshToken	string

Response:

Params	Values
message	string
userId	string
auth	string
refreshToken	string

Send Notification

For sending notifications.

Request:

Method	URL
POST	/sendNotification

Params	Values
notifications	[ { "customStudyId": string, "notificationText": string, "notificationTitle": string, "notificationType": string, "notificationSubType": string } ]

Response:

Params	Values
message	string

App Properties

For setting the properties of the app.

Request:

Method	URL
POST	/appPropertiesUpdate

Params	Values
appId	string
orgId	string
androidBundleId	string
androidServerKey	string
iosBundleId	string
iosCertificate	string
iosCertificatePassword	string
email	string
emailPassword	string
registerEmailSubject	string
registerEmailBody	string <refer to Appendix - Email Body>
forgotPassEmailSubject	string
forgotPassEmailBody	string <refer to Appendix - Email Body>
feedbackEmail	string
contactUsEmail	string
appName	string
methodHandler	string

Response:

Params	Values
message	string

Appendix - Email Body

The body of the emails need to be in HTML format and the <<< TOKEN HERE >>> part represents an identifier for the verification code or temporary password dynamically generated for that email. All fields in the API are mandatory.

Register Email Body

Email subject for signup mail, replace ‘xxxxxx’ with your organization’s name that is offering the app, or other suitable text.

<html>
<body>
<div style='margin:20px; padding:10px; font-family: sans-serif;font-size: 14px;'>
<span>Hi, </span><br/><br/>
<span>Thank you for registering with us! We look forward to having you on board and actively taking part in<br/>research studies conducted by xxxxxx.
</span><br/><br/>
<span>Your sign-up process is almost complete. Please use the verification code provided below to<br/>complete the Verification step in the mobile app.
</span><br/><br/>
<span><strong>Verification Code:</strong> <<< TOKEN HERE >>>
</span><br/><br/>
<span>This code can be used only once and is valid for a period of 48 hours only.
</span><br/><br/>
<span>Please note that registration (or sign up) for the app is requested only to provide you with a <br/>seamless experience of using the app. Your registration information does not become part of <br/>the data collected for any study housed in the app. Each study has its own consent
process <br/> and no data for any study will be collected unless and until you provide an informed consent<br/> prior to joining the study </span><br/><br/>
<span>For any questions or assistance, please write to <a>Contact Email Address</a> </span><br/><br/>
<span style='font-size:15px;'>Thanks,</span><br/>
<span>The xxxxxx Team</span><br/>
<span>----------------------------------------------------</span><br/>
<span style='font-size:10px;'>PS - This is an auto-generated email. Please do not reply.</span>
</div>
</body>
</html>

Forgot Password Email Body

Email Body for Password Help email, replace ‘xxxxxx’ with your organization’s name that is offering the app, or other suitable text.

<html>
<body>
<div style='margin:20px;padding:10px;font-family: sans-serif;font-size: 14px;'>
<span>Hi,</span><br/><br/>
<span>Thank you for reaching out for password help.</span><br/><br/>
<span>Here is a temporary password which you can use to sign in to the (app name) App.<br/> You will be required to set up a new password after signing in.</span><br/><br/>
<span><strong>Temporary Password:</strong> <<< TOKEN HERE >>>
</span><br/><br/>

<span>Please note that this temporary password can be used only once and is valid for a period of 48 hours only.</span><br/><br/>
<span>For any questions or assistance, please write to <a> Contact Email Address </a> </span><br/><br/>
<span style='font-size:15px;'>Thanks,</span><br/><span>The xxxxxx Team</span><br/>
<span>----------------------------------------------------</span><br/>
<span style='font-size:10px;'>PS - This is an auto-generated email. Please do not reply. In case you did not request password help, please visit the app and change your password as a precautionary measure.
</span>
</div>
</body>
</html>