SMS Phone Verification

As users interact with your mobile apps and websites, it's often useful to collect phone numbers and verify their legitimacy. With verified phone numbers, you can place a barrier in front of bot traffic, and make sure you're sending information to the right users.

# In this article

# Overview

If your Iterable project uses Iterable SMS, you can use Iterable's SMS phone verification feature to verify phone numbers. To do this:

1. This is an add-on feature. Contact your customer success manager for pricing and to set up SMS verification in your Iterable project.
2. Collect user phone numbers on your website or in your mobile apps, wherever it makes sense to do so.
3. After collecting a user's phone number, send them a verification code by calling Iterable's API from your server.
4. Have the user to enter their code back in your website or mobile app.
5. Validate the user's code by having your server call Iterable's API.

# Things to remember

As you're working with SMS phone verification, remember:

• If you use your own Twilio or Telnyx accounts to send SMS messages with Iterable, call their SMS verification APIs directly (Twilio, Telnyx). No need to call Iterable's API.
• Verification codes are sent from a pool of sender IDs reserved for this use, not from your sender IDs. Because of this, you don't need to worry about message priority for SMS campaigns vs verifications, or other throughput concerns.
• There is an added cost for this feature. Work with your customer success manager to understand the implications for your account.
• Only call Iterable's SMS verification APIs from your server, not from front-end code (web, mobile, or otherwise).
• When collecting phone numbers on your website or in your mobile apps, do not save them to Iterable unless your users give you explicit consent to do so (by reading legal-approved language and enabling a toggle). Collecting phone numbers for verification purposes is not the same thing as receiving consent to send SMS messages to those numbers.

# Configuring your Iterable project

To set up SMS phone verification in Iterable:

1. Ask your Iterable customer success manager to enable this feature for your Iterable project. Be sure to mention:

   • How long of a verification code you'd like to send when verifying phone numbers (4-8 digits)
   • The rest of the text you'd like to include in the message.

2. Your customer success manager will use the information you provide to configure Iterable SMS and set up a verification profile for you to use. A verification profile is a bundle of configuration settings related to the text you'd like to use for your SMS verification messages, and the number of digits your verification codes should contain.

3. Sign in to your Iterable project and enable the verification profile set up by your customer success manager:

   • Navigate to Settings > Sending Platforms.
   • Open the SMS account Iterable should use for sending SMS verification codes.
   • In the overflow menu (three dots), click Add Verification Profile.
   • In the Add Verification Profile window, find the new verification profile and click Connect.
   • Close the Add Verification Profile window.

4. Grab the ID of the new verification profile, which you'll need when calling Iterable's SMS verification APIs. To find it, open the Verification Profiles menu, find the verification profile in question, and look in the right-hand column.

# Updating your website and mobile apps

To verify phone numbers, work with your design and engineering teams to make various updates to your website and mobile apps, wherever it makes sense.

# Step 1: Collect a phone number

First, update your website or mobile apps to collect phone numbers. This might happen during account sign-up, or at some other point in a user's account lifecycle.

# Step 2: Send a verification code

After your website or mobile apps collect a phone number, send it to your server. Then, your server can call POST /api/verify/sms/begin to send a verification code. Here's a sample request body:

{
  "verificationProfileId": 12345,
  "phoneNumber": "+14155550132"
}

In this request:

• verificationProfileId is the ID you retrieved above, on the Settings > Sending Platforms page in Iterable.
• phoneNumber is the phone number you'd like to verify, which receives a verification code in an SMS message. The phone number should be a string, prefixed with + and a country code.

Notice that this request body doesn't identify a user profile in Iterable. Verify requests aren't related to specific user profiles — they just send verification codes to whatever phone number you provide.

# Step 3: Collect the user's verification code

After the user receives the verification code, they should enter it into your website or mobile app, so you can verify that it's correct. Work with your engineering teams to add this input wherever necessary.

# Step 4: Verify the code

To verify that the user's code is correct, send it to your server. Then, have your server call the POST /api/verify/sms/check API endpoint. Here's a sample request body:

{
  "verificationProfileId": 12345,
  "phoneNumber": "+14155550132",
  "code": "13579"
}

In this request:

• verificationProfileId is the ID you retrieved above, on the Settings > Sending Platforms page in Iterable.
• phoneNumber is the phone number to which the verification code was sent.
• code is the code entered by the user.

This endpoint doesn't include any information about a user profile, either.
That's because it isn't related to an Iterable user profile. Instead, it just verifies the code sent to a specific phone number.

To indicate a successful verification, the API returns a 200 response with a response body that has a params object where status is verified:

{
    "msg": "",
    "code": "Success",
    "params": {
        "status": "verified"
    }
}

To indicate an unsuccessful verification, the API returns a 200 response with a response body that has a params object where status is rejected:

{
    "msg": "incorrect verification code",
    "code": "Success",
    "params": {
        "status": "rejected"
    }
}

After a code has been successfully verified, it cannot be verified again.

# Usage and Billing Metrics

For usage and billing purposes, Iterable tracks successful SMS verifications, not unsuccessful ones.

This number is displayed on the Settings > Usage & Billing in the Messaging Usage section, in the Successful SMS Verifications column.

For more information, read Usage and Billing.