OneSignal Help & Documentation

Welcome to the OneSignal New IA developer hub. You'll find comprehensive guides and documentation to help you start working with OneSignal New IA as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    Discussions

Import Phone Numbers

How to add Phone Numbers to use OneSignal SMS feature

OneSignal provides the following ways to add phone number records into your account:

Import Option


Dashboard Upload

Best if you have a CSV list of phone numbers and want to upload through the dashboard without code.

API Add a device

Use the Add a device endpoint to set the device_type = 14 and the identifier as the phone number in E.164 format. Any other data you want to add is optional.

SMS SDK Methods

Can be used for long-term implementation on the client side.

Email & Phone Number Web Prompt

A web prompt that allows user to include their own phone number and email address.

Import Phone Numbers through Dashboard

Navigate to Audience > All Users > Update/Import Users

Select Upload CSV next to "Import phone_number(s)".

Import Phone Number CSV columns




Required: must be in the E.164 format


Required: identifier that can be used to uniquely identify a user. See External User Ids for more details.

If you need help ensuring your CSV is in the correct format, download our template using CSV Template download button.

Note: The first row should have the column labels exactly matching the above Property names. The order does not matter.

Example CSVExample CSV

Example CSV

You can automatically create a new segment for the imported list. This adds a tag to the newly imported list and auto-creates a segment based on the input value. For example, "SMS_Subscriber_Test_List" in the above image.

Once you Confirm and Import, you will get an email with the results from the CSV Import.


You cannot have multiple phone numbers associated with an external_user_id. If the external_user_id exists, then we will replace the old phone number with the new one.

You cannot have the same phone number associated with multiple external_user_id. Only the last provided external_user_id will be linked with the phone number.

Please reach out to OneSignal support if you prefer to have multiple phone numbers for a given external_user_id.

Update User Records

To add or update custom attributes for the Phone Number records, keep the current CSV and add additional columns for tags. See Importing User Attributes or Tags for more details.

Updated 3 months ago

Import Phone Numbers

How to add Phone Numbers to use OneSignal SMS feature

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.