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 CommCare's API Authentication Documentation.

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": []