Troubleshoot the Contact API

Even though the Contact API import setup is customised to meet your company's data requirements, the following conditions are required for successful file import.

CSV file format is comma delimited

Whispir only supports the import of comma delimited .CSV files. Text fields with commas as part of the data should use quotation marks (" ") around the data.

CSV file name format must follow the agreed format

Once Whispir and your company have agreed on a .CSV file name format, that file name must always follow that format for every import. It is something like <YourCompanyName>_<Time>_<Date>_<Count>records<Import Option>.CSV.

CSV file headers must remain the same

Once Whispir has worked with you to determine the correct .CSV data file format for your data, the format of the .CSV file header must be exactly the same for every import with the same number of columns, column names and order.

Contacts are imported into a single Whispir workspace called ‘Masterlist’

A single administration workspace is created specifically to hold the contacts imported via the Contact API. This is called the ‘Masterlist’. From here contact mapping rules are used to map contacts to the workspaces they need to be in for receiving messages.

The Masterlist workspace is the only workspace configured to allow a Contact API import. All other workspaces can only use Whispir’s standard contact import functionality and this will only work if your company has not implemented custom contact profile fields. For more information contact the Whispir Support Team (

It’s possible to perform a manual Contact API import into the Masterlist if SFTP is not an option or is unavailable.

Each contact must have a unique identifier

You can specify what type of unique identifier is used for your contacts in the initial data file design. For all imports an identifier must exist for each individual contact and it must not change. This identifier is used to compare the contact record imported from the previous import and determine if the record is new and has to be added, is existing and has to be updated, or is existing but has to be ignored as no change is identified. Any contacts in the Masterlist workspace that are not in the import file are deleted.

A full and complete listing of the contacts to be maintained in Whispir must be in the .CSV file for each import

The Contact API processing deletes all contacts in the Masterlist that aren’t in the .CSV file being imported up to a standard threshold of 5% of the Masterlist contacts. This is a safety mechanism that stops the import process at that threshold to ensure contact details aren’t being deleted due to a file import error.

The threshold can be configured by the Whispir Support Team ( For example, a company might request a temporary increase in the threshold to 100% to process a high number of deletions in a one-off import.

Whispir's standard contact import functionality does not delete contacts.

Contact mapping rules must be in place

In order to make the contacts available in other workspaces, contact mapping rules must be in place to map from the Masterlist. Whispir will work with you to ensure these rules are set up before the initial import. See About Contact Mapping Rules.

Mandatory fields must have data

The mandatory data fields will depend on the custom configuration for your company. Once agreed, these fields must always have data in the imported .CSV file. At a minimum, Contact Last Name and Unique Identifier are mandatory.

Data must be message-ready

The Contact API doesn’t perform data validation, data integrity or data quality checks. All contact information should be complete and ready for the type of messaging the contacts require. In particular phone numbers should be valid and meet specified formats with no invalid characters. Phone country codes should exist for each phone number being imported.

Data used in any dynamic distribution lists must be included. See Create a dynamic distribution list.

Contacts imported via the Contact API can’t be edited or deleted via the Whispir platform

Once the Contact API has been implemented for your company, the ‘source of truth’ for contact data is assumed to be external to the Whispir platform. As a result any contact record updates (add/edit/delete) must be made in the source system(s) and then the updated data is imported.

Avoid allowing users to add, edit or delete contacts via the Whispir platform once Contact API is implemented. It can cause confusion when users believe they’ve updated a contact, only to find it has reverted or changed following a later import from the source system.

Whispir can advise on how to adjust workspace permissions to disable the add, edit and delete functions in workspaces that use Masterlist contacts. For information about permissions see About roles and permissions.

New workspaces or new contact mapping rules created after Contact API implementation

New mapping rules and a manual contact mapping are required when workspaces are added or new or changed rules need to be applied. See Create a workspace mapping rule.

View the Activity Log to check import status

Company administrators can open the Activity Log from the Administration sidebar.

On the Activity Log page use filters to search for an entry noting that a file has been accepted for processing. A corresponding entry will show the number of records added, updated, deleted and ignored during processing. The activity log also shows the status of each record processed.

Related links