SMS Mobile Worker Registration API

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

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

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

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):

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

Sample input (complex):

{
  "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:

{
  "success_numbers": ["+16175551234"],
  "invalid_format_numbers": [],
  "numbers_in_use": []
}