Skip to content

User phone numbers

This article will discuss different topics around your users’ or customers’ phone numbers. If you’re looking for information about your own numbers, go to our article on sending phone numbers.

Phone numbers are shown in the user profile in local formats, but will not be in the format you use to import the number ((724) 123 4567).

Importing phone numbers

You can import phone numbers by uploading a CSV or via API to create a user.


As a best practice, the best way to import a phone number is in E.164 format. However, Braze will attempt to interpret or convert any U.S. number to the best of our ability.

All U.S. numbers must be valid, 10-digit phone numbers with a valid area code. They can be input without the + and country code, as Braze will assume and map all valid, 10-digit phone numbers as U.S. numbers.

All international numbers should start with a +, followed by their country code and then the phone number. (e.g +442071838750)

However, to ensure accuracy in the event that you are sending to multiple regions with different country or area codes, it is recommended to use the E.164 format, even for U.S.-based phone numbers.

You can see the differences between local number formatting as well as universal, E.164 formatting in the following table:

Country Local Country Code E.164
USA 4155552671 1 +14155552671
UK 2071838750 44 +442071838750
Brazil 1155256325 55 +551155256325

Adding users to SMS subscription groups

For a customer to receive an SMS message, they must have a valid phone number and be opted-in to a subscription group. Subscription groups are tied to the SMS program you are running (make sure you follow the legal requirements for SMS and have recorded consent for each customer). For more information, refer to SMS subscription groups.

Handling invalid phone numbers

When a phone number is deemed invalid, Braze will mark the user’s phone number as invalid and will not attempt to send further communications to that phone number. An invalid phone number is marked in the Engagement Tab of a user profile.

A phone number is considered invalid for the following reasons:

  • Provider Error: a permanent error was received from the SMS provider. This indicates that the phone number supplied is incorrectly formatted or permanently unable to receive SMS messages.
  • Deactivated: the phone number has been deactivated due to a mobile subscriber terminating their service and releasing their number from their carrier (and may eventually be recycled and assigned to a new user).

These invalid phone numbers can be managed using SMS endpoints.

You can also include or exclude any users with invalid phone numbers when creating a segment.

Third-party sourcing and verification

Braze relies on third-party tools to source invalid numbers. Braze is not responsible for any outages or misinformation of these services. Thus, this tool should not be relied upon as your sole method of compliance for verifying invalid numbers.

New Stuff!