Skip to main content

How-to guide for bulk upload

  • Updated

Table of contents

What you’ll need

  • The Hiya Connect bulk upload template - download it here
  • Your list of phone numbers with any Call Branding details you’d like to apply
    • Your bulk upload file can contain new, previously unregistered phone numbers 
    • Your bulk upload file can also include numbers already in your account. These numbers will be updated with the new information contained in your bulk upload file. 

Getting started

  1. Open the template file
    • After downloading the bulk file CSV template, open it in your spreadsheet editor of choice. Your spreadsheet program may change the file format during editing. This file format change should not cause problems, but your file must be saved as a CSV before uploading.
    • The CSV template contains 8 columns.
      Note: Customers using managed brands will see an additional 9th column 
  2. Do not delete the first row
    • This row contains the header for each column and must be included.

Add your phone numbers

  1. Start with the 2nd row and the 2nd column:
    Add your phone numbers without the country code and without additional characters
    • In the 2nd column, enter each of your phone numbers into separate rows. Do not include the numerical country code (e.g. +1, +44, +283)
    • Example: +1 (206) 867 5309 is entered as 2068675309
    • You can add as many numbers/rows as you need
  2. Add the 2-letter country code for each number
    • Add the country code in the 1st column
    • Example: the country code for +1 (206) 867 5309 would be US
    • Example: the country code for +44 303 123 7300 is GB

Add your Call Branding and display details

  1. Add the State (US only) and City for each number (optional) 
    • If you wish your location to be shown on caller displays differently than the location associated with the country and area code, enter the details in these columns.
    • States can only be added for US phone numbers. This detail will be ignored for non-US numbers.
    • The city and state entered here may not show up on all displays. Some carriers will continue to display the location associated with the country code and area code of the phone number.
  2. Add the business display name (required)
    • Enter the business name that represents your company on a call recipient’s display
    • There is a max length of 32 characters
    • The business name cannot contain a comma
    • To avoid disapprovals and delays, make sure your business name adheres to Hiya’s Content Guidelines
  3. Add a caller image ID (optional) 
    • For Hiya Connect users who have have existing phone numbers in their account, you can apply an image that it already in your account
    • To find a caller image ID already in use in you Connect account, visit your image library
    • Copy the caller image ID string from an image in your library and paste it into the cell for the phone number you would like to share that image
  4. Choose to use the caller image from default call branding (optional)
    • For Hiya Connect users that have created a default call branding in their account, you can choose to apply the image associated with your default branding
    • If you wish to use the image associated with that display, enter Y in the cell
    • If you do not wish to use the associated image, enter N or leave the cell empty
    • Learn more about the default call branding in the help center
  5. Add a call reason (optional)
    • Enter a brief description that clearly indicates the reason for your call.
    • There is a max length of 50 characters
    • The call reason cannot contain a comma
    • To avoid disapprovals and delays, make sure your call reason adheres to Hiya’s Content Guidelines
    • This attribute may be overridden for calls made using the Hiya Connect API
For customers using the Managed Brands feature
  1. Include a managed brand  (required) 
    • An additional column is included in the template to accommodate managed third-party brands
    • Enter the name of an approved managed brand
    • All uploaded phone numbers must include a managed brand
    • To avoid errors, the brand must be available in the “Approved” list in your account’s Managed Brands 

An example of a properly formatted upload file

Save (or export) your file as a CSV

In order to upload your list of phone numbers, you must save your edited spreadsheet as a CSV file. This is a common file format and all common spreadsheet programs include the ability to save or export to this format.

In general:

  1. Open the “File” menu
  2. Select “Save as…” or “Export”
  3. Select the CSV file format option
  4. Save the file to your computer

See the appendix for screenshots from some common spreadsheet tools.

Upload your CSV file

  1. Navigate to the bulk upload tab on the “Add phone numbers” page in the Hiya Connect console
    • Click the “Add numbers” button in the main navigation of the Connect console
  2. Drag your file to the upload area or browse your computer for your CSV file
  3. Choose whether you would like to ignore or update existing phone numbers
    • When uploading your CSV file, you will be asked how you would like to handle phone numbers that already exist in your account.
    • If you would like to ignore those phone numbers and maintain the existing branding and display details as they are in your account, select “No, ignore existing numbers”
    • If you would like existing numbers to be updated with the branding and display details from your CSV file, select “Yes, update existing numbers”
  4. Click “Begin upload”

Appendix: Exporting a CSV from common spreadsheet tools

Microsoft Excel

Apple Numbers

Google Sheets

Appendix: Troubleshooting

Common formatting errors

  • Country code
    • Proper format: US
    • Do not use the numerical country code
    • Do not use the full country name
  • Phone numbers
    • Proper format: 2068675309
    • Do not include non-numerical characters such as + - (  or )
    • Do not include the numerical country code (e.g. +1, +44, +283)
  • State
    • Proper format: WA
    • Use only a two-letter abbreviation. Do not use the full state name.
  • City
    • Proper format: Seattle
    • Include only the city name. Do not include the state in this column.

Visit Hiya’s Content Guidelines for complete details on proper formatting.

Caller image ID / Caller image from default display

  • When including an image, use only one of the 2 available columns.
  • To use a specific image ID, include it in the “Caller image ID” column. Do not enter a “Y” in the “caller image from default display” column. 
  • If the caller image ID matches the image from your default display, use either one of the two columns but do not use both.

Managed brands (only for customers managing third-party brands)

  • Make sure the managed brands included in your upload are already available in the “approved” tab in your account’s Managed brands 
  • Make sure the spelling in your account matches the spelling in the upload CSV

Every phone number must include a managed brand. Phone numbers that do not include an approved managed brand will result in an error.