Example Files

These are working examples of a contact file in each supported format. All three describe the same three contacts with the same values, so the structures can be compared directly and whichever format the source system exports can be used. Take one as a starting point and replace the rows with real data.

For the rules these files have to satisfy, including accepted formats, limits and how validation failures surface, see Contact Files.

What the Example Contains

The example file has six columns. What each one does is decided when it is mapped, not by what it is called, so the headings below are only the ones this example happens to use.

Column	Mapped to	Notes
phoneNumber	Phone Number	The identifier an SMS campaign sends to. Must be in E.164 format
email	Email	The identifier an email campaign sends to. A well-formed address
name	First Name	The sample holds a full name, so split it into First Name and Last Name columns to keep the two apart
amountOwed	A custom field	Create the field first, see Creating a custom field
dateOwed	A custom field	As above, and typed as Date so it can be compared in a segment
priority	Priority	High or Normal, see Message Priorities

The same file works for either channel: it carries both a phone number and an email address, and the campaign's channel decides which one is used. Any column with no matching field can be left out of the mapping entirely.

amountOwed and dateOwed show how data specific to your organisation reaches a message. Each is held on the contact in a custom field and is then available as a variable in a template.

The column headings are yours to choose

phoneNumber, phone_number, mobile and msisdn are all equally valid headings for the same column. Only the mapping matters, not the naming.

CSV

One row per contact, with a header row naming the columns:

name,email,amountOwed,dateOwed,phoneNumber,priority
John Smith,john.smith@example.com,250,1/7/2025,+61400111222,High
Jane Doe,jane.doe@example.com,500,15/7/2025,+61400333444,Normal
Alex Brown,alex.brown@example.com,100,30/7/2025,+61400555666,Normal

JSON

A flat array of objects, one object per contact:

[
  {
    "name": "John Smith",
    "email": "john.smith@example.com",
    "amountOwed": 250,
    "dateOwed": "1/7/2025",
    "phoneNumber": "+61400111222",
    "priority": "High"
  },
  {
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "amountOwed": 500,
    "dateOwed": "15/7/2025",
    "phoneNumber": "+61400333444",
    "priority": "Normal"
  },
  {
    "name": "Alex Brown",
    "email": "alex.brown@example.com",
    "amountOwed": 100,
    "dateOwed": "30/7/2025",
    "phoneNumber": "+61400555666",
    "priority": "Normal"
  }
]

There is no wrapper object and no nesting: the array is the whole document, and every object holds a flat set of values.

XML

A <contacts> root element wrapping one <contact> element per contact, with each value as a child element:

<?xml version='1.0' encoding='utf-8'?>
<contacts>
  <contact>
    <name>John Smith</name>
    <email>john.smith@example.com</email>
    <amountOwed>250</amountOwed>
    <dateOwed>1/7/2025</dateOwed>
    <phoneNumber>+61400111222</phoneNumber>
    <priority>High</priority>
  </contact>
  <contact>
    <name>Jane Doe</name>
    <email>jane.doe@example.com</email>
    <amountOwed>500</amountOwed>
    <dateOwed>15/7/2025</dateOwed>
    <phoneNumber>+61400333444</phoneNumber>
    <priority>Normal</priority>
  </contact>
  <contact>
    <name>Alex Brown</name>
    <email>alex.brown@example.com</email>
    <amountOwed>100</amountOwed>
    <dateOwed>30/7/2025</dateOwed>
    <phoneNumber>+61400555666</phoneNumber>
    <priority>Normal</priority>
  </contact>
</contacts>

The whitespace is only for readability. The element names and the structure are what matter, and the file works equally well on a single line.

Using an Example

1. Save the example in the format you want, with a .csv, .json or .xml extension.
2. Replace the sample contacts with your own, keeping the column headings consistent across every row.
3. Create any custom field the file needs, so there is something to map its extra columns to.
4. Upload it, either with the Upload Contacts wizard or as a campaign's File audience.
5. Map the identifier for the channel, the columns you want to personalise with, and optionally the priority column.

A row is skipped if it has no usable identifier for the channel, or if that value is badly formatted. A blank in any other column does not skip the row, and priority is read as normal priority when its value is missing or unrecognised. See What makes a contact invalid.

Use real consent, not sample data

The addresses and numbers above are examples and will not deliver. Before uploading real contacts, confirm you have consent for every contact in the file. You are asked to accept this explicitly before the upload begins.

Related Guidance

• Contact Files. Accepted formats, what a row needs, limits and validation rules.
• Message Priorities. What the priority column does.
• E.164 Phone Number Format. Required format for SMS phone numbers.
• Uploading Contacts. Importing a file into the contact store.