Skip to main content

Implementing changing of user's email address or mobile number

This example shows how to implement email address or mobile number switching, so that the new address/number is verified and the old number is either kept or replaced.

This process can be implemented as a web page or an application. You will be using two Management API endpoints to perform the action.

Ask the user for their new contact information​

Implement a web page or show the user a form where you ask for their new email address or mobile number.

Call the “begin” API​

Call the /api/rest/v1/user/{userId}/change-contact/begin API to begin the process. You can call it with API Client credentials or the user’s own access token. See exact authentication details in the API documentation.

You can configure the request so that the new address/number will become the primary address/number, or that it replaces all previous addresses/numbers.

The API will send a verification message to the provided address/number.

The response from this endpoint will supply you with a verification token and information about how long the verification is available.

There are limitations on how many verification messages can be sent to a single address/number per 24 hours. There are also limits on how many messages per user account can be sent.

Ask the user for their verification code​

Show the user a text field where they can enter the verification code they will receive shortly. The code is a 6 digit numeric code.

Send the code to the verification API​

After the user has provided the code, you will send it together with the verification token to the /api/rest/v1/user/{userId}/change-contact/finish API.

If the code is correct, the user data will be changed in the ID service and you will receive updated user information.

If the code is incorrect, you will receive an error response. Tell the user to restart the process.

Note that the verification code for a specific address/number can only be entered once. After that a new verification code must be sent.

After the change​

The new address/number will be marked as verified.

You can read the up-to-date contact information from the API response. You can also use the userinfo endpoint as well as other APIs to update your data.