The operation POST /environments/{environmentId}/users/{userId}/devices adds a new SMS MFA method to the specified user resource.

The status parameter is optional. Use cases:

  1. If the actor makes the request on behalf of another user, the value assigned to status can be one of:
  2. If the actor making the request is the same user for whom the device is created, the status can only be ACTIVATION_REQUIRED (default, if not provided). Thus in this case, a user is required to activate the device before performing its first authentication.

If the status is ACTIVATION_REQUIRED, you can use the notification property during device creation to create a custom device pairing notification. Only applicable with SMS and Email devices. This property is not returned with GET operations and cannot be used with PUT operations. For more information, see Custom device pairing notification with device creation.

A valid phone number string can be provided in international format (includes a leading + character), or in any format as long as the region (country code) where the number originates can be determined. The input string is checked to determine whether it is a viable phone number (for example, whether it has too few or too many digits, cannot start with a 1) or if no country code is supplied.

The following sample shows acceptable valid phone attribute formatting for the same number:

+1.5125201234
+15125201234
+1.512.520.1234
15125201234
1-512-520-1234
+1 (512) 520-1234