Importing Contacts from a File

Load a spreadsheet of people: what the formats are, how columns are matched to fields, what the preview tells you, and how to undo an import that was wrong.

Before you start

Import is under Recipients → Contacts → Import, or from the Import button on any recipient list if you already know which list these people belong on.

You will need a file with one person per row and a heading row at the top. Anything with a column of mobile numbers will do — the headings do not have to match anything in particular, because you map them yourself in a moment.

Name,Mobile,Student ID,Tutor,Campus
Ada Lovelace,07911 123456,S1049823,Dr Patel,Highfield
Grace Hopper,07911 123457,S1049824,Dr Ng,Avenue

CSV — the plainest option and what most systems export.
Excel (.xlsx) — the first worksheet is read. See "What spreadsheets do to phone numbers" below, because this is the safer of the two.
XML — whatever your student or HR system produces. The repeated element becomes the row and its child elements become the columns; no particular schema is required.

Up to 20,000 rows and 10MB per file. For anything larger, split it and import the parts — or use the API, which has no such ceiling.

Nothing is written until you say so

The import runs in four steps: choose the file, map the columns, review what will happen, then apply it. The file is read in your own browser, and even after the review has been prepared no contact has been touched. You can back out at any point up to pressing Import and nothing will have changed.

1. The file

Choose the file, and optionally the list everybody should join. You do not have to pick one — an import with no list simply loads the people, and you can put them on lists later.

If you have imported a file like this before, pick the saved mapping instead and the columns and settings come with it.

Make the list match the file exactly

This one is worth reading twice. Normally an import only adds people. Turn this on and it also removes anyone on the list who is not in the file, so the list ends up matching the file exactly. Useful for a roster you re-export every month; damaging if you upload a partial file by accident.

The people removed stay contacts and stay on their other lists — only this list's membership goes. The review tells you how many that is before you commit, and an import that would empty a list without adding anybody is refused outright.

2. The columns

The columns are matched to fields for you, by heading. "Mobile", "Mobile No.", "Phone" and "Contact Number" all find the number; "Student ID" and "Reference" find your own identifier. Anything it is unsure about is left as "Don't import" for you to set. If no heading looks like a phone number, it reads the values instead and picks the column that actually contains numbers.

A column with no matching field can become one. New field creates it on the spot, working out from the values whether it holds text, a number, a date or a fixed set of options, and maps the column to it — so you do not have to abandon the import, declare a field elsewhere and start again.

This step is also where you choose what happens to people you already hold, and whether to accept test numbers. Both are covered under duplicates.

What happens to people you already hold

Saving the mapping

Give the mapping a name and save it, and the next file with the same headings needs no mapping at all — pick it on the first step and go straight to the review. It remembers the columns, the target list, how conflicts are handled and whether the list is reconciled.

Worth doing for anything you import regularly. A monthly extract that took ten minutes to map the first time becomes a thirty-second job.

3. The review

Your rows are read and checked against the contacts you already hold, then grouped by what will happen to each. Every group opens, so you can page through the actual rows rather than trusting a total:

New contacts — nobody holds these numbers yet.
Existing contacts to update — matched to somebody you already have.
Number changes — your reference matched, but on a different number.
Number changes that cannot be applied — the new number already belongs to somebody else.
Duplicated within the file — the same person appears twice, and the later row wins.
Rows that cannot be read — reported, never silently dropped.

Rows that cannot be read, and number changes that cannot be applied, can be downloaded as a CSV carrying your original columns plus a Reason column. Fix them in that file and import it on its own.

If most of the file cannot be read, the import is stopped rather than partly applied. That almost always means a column is mapped to the wrong field — a column of student numbers mapped to the phone number, for instance. Go back a step and check.

4. Applying it

Press Import. Large files are applied in batches with a running count, and everyone in the file joins the list whatever you chose to do about their details.

Undoing an import

Every import can be undone. Undo this import appears as soon as it finishes, and afterwards under Recipients → Imports, which lists every import with what it changed.

Undo puts back everything the import touched — contacts it created are removed, contacts it changed go back to what they were, numbers it moved move back, and list memberships it added or removed are restored. What it cannot do is unsend: a message already sent to those people stays sent.

Undo is available for a limited period after an import, so a wrong file is worth undoing rather than fixing by hand. Both the import and the undo stay in the audit trail.

What spreadsheets do to phone numbers

This is the single most common cause of a failed import, and it has nothing to do with our end. A column of mobile numbers is a column of digits, and a spreadsheet treats digits as a number to be tidied up.

You typed:      07911 123456
Excel stored:   7911123456        (the leading zero is gone)
Excel showed:   7.9111E+09        (and the display is rounded)

A missing leading zero is recoverable and we put it back, telling you we have. Scientific notation is not: by the time a CSV has been exported showing "7.9111E+09", the last digits are genuinely not in the file, and no amount of parsing brings them back. Those rows are rejected with an explanation rather than guessed at, because a guess produces a real number belonging to a stranger.

Send us the .xlsx, not a CSV exported from it. A spreadsheet stores the full number and only displays the rounded version, so the .xlsx still has every digit. A CSV exported from the same sheet has the rounding baked in.

If CSV is your only option, format the phone column as Text in the spreadsheet before you export it. That stops the tidying up at source.

Numbers that are rejected

Landlines — SMS cannot be delivered to one, so they are reported rather than stored.
Numbers that are not in service — a well-formed number in a range no network has allocated.
Anything unrecognisable — "ask reception", an empty cell, a date that ended up in the wrong column.

UK numbers can be written however your source system writes them. All of these are read as the same number:

07911 123456
07911123456
+44 7911 123456
+44 (0)7911 123456
447911123456
7911123456

Testing with example numbers? Ranges like 07700 900xxx are reserved for use in drama and documentation and are not in service, so they are rejected. Turn off Only accept numbers in service on the columns step to load them.

People who have opted out

An import never changes anybody's consent. Somebody who has opted out is still added to the list — so your roster matches your source system — and stays opted out, and the review counts them so you know how many of the people you have just loaded you cannot actually message.

Next: how duplicates are handled