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.

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

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 for Android users."abcd1234abcd1234"
userslist of json objectsYesA 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_onlyboolNoSet 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_emailboolNoSet 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_messagestringNoA 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:

NameTypeRequiredDescriptionExample
phone_numberstringYesThe user's phone number, in E.164 format+16175551234
custom_user_datajson objectNoCustom user data to be set to the user when the user registers{"my_custom_field": "my_custom_value"}

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"]
numbers_in_uselist of stringList 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": []
} 

 

 

  • No labels