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.
Authentication: For more information, please review CommCare's API Authentication Documentation.
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:
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| app_id | string | Yes | The unique identifier used by CommCareHQ to identify the app that will be installed on the user's phone | "abcd1234abcd1234" |
| users | list of json objects | Yes | A 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_message | string | No | A 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:
| Name | Type | Required | Description | Example |
|---|---|---|---|---|
| phone_number | string | Yes | The user's phone number, in E.164 format | 16175551234 |
Output Structure:
| Name | Type | Description | Example |
|---|---|---|---|
| success_numbers | list of string | List of phone numbers representing the users that were successfully processed. | ["16175551234"] |
| invalid_format_numbers | list of string | List of phone numbers that could not be processed because they were in an invalid format. | ["1617JKL1234"] |
| error_numbers | list of string | List 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": []
}
