Fix contact CSV imports and Tanzanian phone-number formatting

A contact import is ready for messaging only when names, complete phone numbers and custom values are attached to the right people. A successful upload confirms that rows were accepted; it does not verify that a number belongs to the intended customer or that the source data was accurate.

Prepare a small, checked sample before importing the full list. This is especially useful when a spreadsheet has removed leading digits, changed number formatting or used column names from another system.

Prepare the destination group

Your role needs permission to import contacts into the relevant group. Open Contacts, create or select the destination group, and confirm its purpose. Examples include “Workshop appointments this week” or “Parents attending the open day.”

Create the group's custom fields before importing. A field's label is what people see; its key is what the importer matches. For an order reference, a useful key is order_reference. For a venue, use venue. Keep keys stable if a campaign already refers to them.

The importer expects a comma-separated file with at least name and phone_number headers. It also recognizes country_code, is_subscribed and headers matching custom-field keys. The upload accepts CSV or text files up to 5 MB; an Excel workbook should be exported to CSV first.

Format Tanzanian numbers deliberately

Set spreadsheet phone columns to text before entering or pasting numbers. This helps preserve leading digits and avoids scientific notation. Changing a damaged value's format back to text does not recover digits already lost; compare it with the original source.

For a Tanzanian number, use 255 in country_code and the national part without the initial local 0 in phone_number. The importer strips non-digit formatting and normalizes leading zeros when a country code is provided. If the phone column already starts with that same country code, it removes the repeated prefix for storage.

Do not rely on the importer to infer a country from a local number when country_code is blank. It also does not verify ownership or reachability. Inspect the complete number after import and test using a number you control.

This fictional example illustrates the columns only. Replace the example number with your verified test recipient before using the file:

name,country_code,phone_number,is_subscribed,order_reference
Example Customer,255,700000000,1,EX-104

The intended complete display is +255700000000. A source written locally as 0700000000 needs the country context; it should not be treated as an international destination on its own.

Import and inspect a small sample

1. Check the CSV's first row for the exact headers. Use comma separators, and quote a cell containing a comma, such as "Example Customer, Accounts".
2. Confirm that custom fields already exist in the destination group and that their keys match the corresponding headers.
3. Include an explicit is_subscribed value where you track subscription: 1 for checked or 0 for unchecked. Omitting the column causes imported contacts to default to subscribed.
4. Open the group, choose Import, select the prepared file and complete the import.
5. Read the result showing imported rows and any skipped duplicates or invalid rows. Do not assume skipped rows were updated.
6. Inspect contacts from the beginning, middle and end of the sample. Check complete numbers, names and every field used by the planned message. Use Export, when permitted, to compare stored values with your source.

After the sample checks pass, repeat with the remaining prepared rows. Keep the source list available so you can reconcile the imported count.

Understand duplicate and update behavior

Duplicate detection uses the normalized country-code and phone-number pair within the destination group. It checks contacts already there and repeated entries in the same CSV. A duplicate is skipped; importing the same number with a corrected name or reference does not update the existing contact.

For example, if EX-104 is already stored and a later CSV changes it to EX-105 for the same number, inspect and edit the existing contact deliberately. Otherwise, a later campaign may continue using EX-104.

The same customer may exist in several groups. Correcting one group's entry does not establish that every other entry was changed, and sending separate campaigns to overlapping groups can contact them more than once.

Troubleshoot the common failures

If required headers are reported missing, inspect the actual CSV rather than the spreadsheet's appearance. Check separators, unexpected characters before name, and whether your export added a byte-order mark. A plain UTF-8 CSV without that prefix is a useful retry format.

If custom values are empty, check that the fields existed before import and the headers match their keys. If rows are invalid, inspect blank or non-numeric phone input. If numbers look plausible but are wrong, compare them with the original source; normalization cannot repair missing digits.

Finally, unchecked subscription does not automatically suppress messaging campaigns. Prepare the target group accordingly and use applicable blocking controls before sending. Continue with contact organization, campaign setup or school announcements.