Overview

Purpose: Use this API to facilitate the reinstallation of CommCare on the phones of already-registered users. All recipients should be on an Android phone.  The users will receive two SMS: one with a link to the Google Play store to download and install CommCare, and one with the CommCare app install information which is used by CommCare internally.

Project Prerequisites: Your project must have a PRO plan or higher to use this feature, and you must enable "SMS Mobile Worker Registration" on the Messaging -> General Settings page.

URL: https://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration_reinstall/

Available since: v0_5

Method: POST


Input and Output Structure

Input Parameters:

NameTypeRequiredDescriptionExample
app_idstringYesThe unique identifier used by CommCareHQ to identify the app that will be installed on the user's phone"abcd1234abcd1234"
userslist of json objectsYesA list of json objects representing the users to send the SMS information to. See below for the structure of each of these json objects.{"phone_number": "16175551234"}
reinstall_messagestringNoA custom SMS message that will be sent instead of the system's default message, containing the link to the Google Play store for the CommCare installation. Be sure to leave a placeholder ("{}") for the link to the Google Play store.

"Click here to install CommCare: {}"

with each json object in the users list having this structure:

NameTypeRequiredDescriptionExample
phone_numberstringYesThe user's phone number, in E.164 format16175551234

Output Structure:

NameTypeDescriptionExample
success_numberslist of stringList of phone numbers representing the users that were successfully processed.["16175551234"]
invalid_format_numberslist of stringList of phone numbers that could not be processed because they were in an invalid format.["1617JKL1234"]
error_numberslist of stringList of phone numbers that could not be processed due to error.["16175551234"]

Sample Usage

Sample input (simple):

{
  "app_id": "abcd1234abcd1234",
  "users": [
    {"phone_number": "16175551234"}
  ]
}


Sample output:

{
  "success_numbers": ["16175551234"],
  "invalid_format_numbers": [],
  "error_numbers": []
} 
  • No labels