Overview
Purpose: Initiate the SMS self-registration workflow for mobile workers. This performs the same functionality as the Messaging -> Mobile Worker Registration page, only over API.
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 https://dimagi.atlassian.net/wiki/x/LwXKfw.
URL: https://www.commcarehq.org/a/[domain]/api/[version]/sms_user_registration/
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 for Android users. | "abcd1234abcd1234" |
users | list of json objects | Yes | A list of json objects representing the users to send the SMS registration invitation to. See below for the structure of each of these json objects. | {"phone_number": "+16175551234"} |
android_only | bool | No | Set to true to have the system assume the users are all Android users. In that case, the system will not ask the users over SMS if they are using an Android phone or not. | false |
require_email | bool | No | Set to true to make email address a required field on the user self-registration page that the Android users will be pointed to. | false |
custom_registration_message | string | No | A custom SMS message that will be sent instead of the system's default message to each of the users when this workflow starts. If android_only is false, be sure to ask the user to enter 1 if they are using an Android phone and 2 for other. If the android_only is true, be sure to leave a placeholder in the message for the registration URL which should look like this: {} | android_only=false example: "Your are receiving this SMS to register with Test Project. Please reply with 1 if you are using an Android phone, 2 for other." android_only=true example: "You are receiving this SMS to register with Test Project. Please click here to begin registration: {}" |
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 |
custom_user_data | json object | No | Custom user data to be set to the user when the user registers | {"my_custom_field": "my_custom_value"} |
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"] |
numbers_in_use | list of string | List of phone numbers that could not be processed because the phone numbers are already registered. | ["+16175551234"] |
Sample Usage
Sample input (simple):
| Code Block | ||
|---|---|---|
| ||
{
"app_id": "abcd1234abcd1234",
"users": [
{"phone_number": "+16175551234"}
]
} |
Sample input (complex):
| Code Block | ||
|---|---|---|
| ||
{
"app_id": "abcd1234abcd1234",
"android_only": true,
"require_email": true,
"custom_registration_message": "Please register a new user here: {}",
"users": [
{
"phone_number": "+16175551234",
"custom_user_data": {
"customdata1": "foo",
"customdata2": "X"
}
},
{
"phone_number": "+16175555512",
"custom_user_data": {
"customdata1": "bar",
"customdata2": "Y"
}
}
]
} |
Sample output:
| Code Block | ||
|---|---|---|
| ||
{
"success_numbers": ["+16175551234"],
"invalid_format_numbers": [],
"numbers_in_use": []
} |
|