Adding Directory Contacts

About Adding Directory Contacts

The Directory contacts tab contains all the contacts added to your organization’s directory. Any contacts added to a mailing list are added to this directory automatically, but you can also add people straight to the directory itself by using the Add contacts button.

---

×

close

Qtip: Contacts added to the directory are visible to every user in the organization with access to the directory.

Qtip: While adding any new contacts, be sure to check out your settings for merging duplicates, which will be visible in the import window. These settings determine how duplicates are identified and combined; these settings can be modified by directory admins.

Projects That Can Use XM Directory Contacts

Qtip: The features discussed in this section are not necessarily included with every license. If you’re interested in getting access, please reach out to your Account Executive.

You can use XM Directory to build contact lists and send invitations for several types of Qualtrics projects. However, not every Qualtrics project type is compatible with XM Directory.

XM Directory can be used to send the following:

• Survey projects
• Conjoint / MaxDiff
• Certain non-EX XM Solutions

Qtip: You can also send emails without a link to any survey.

However, XM Directory contact data is completely separate from the employee / participant information saved in the Employee Directory. That means that data edited in one directory will never affect the other. XM Directory cannot be used to distribute any Employee Experience (EX) projects, including Engagement, Pulse, 360, and more.

Available Contact Fields

Whether you’re uploading a CSV or TSV of contacts or manually typing them out, there is certain information you must include for your contacts.

---

×

close

Qtip: Depending on how your directory merges duplicates, FirstName, LastName, Email, and / or ExternalDataReference may be a required field.

• FirstName: The contact’s first name.
• LastName: The contact’s last name.
• Email: The contact’s email address. It’s recommended that you merge duplicates off this field.
• ExternalDataReference: Extra information about the contact. This is most often used to store data such as an employee or student ID. It can be used to log into authenticators and configure how the directory merges duplicates.
• Embedded data: Embedded data are additional fields containing whatever field you want. These do not have to follow a particular naming convention. In the screenshot above, Department, City, and Country are all embedded data.

  

  Qtip: Embedded data names have a maximum of 200 characters. Values should be a maximum of 1024 characters each.

  

  Warning: All embedded data fields were previously case-sensitive. For a vast majority of users, embedded data is no longer case-sensitive, meaning “test” and “Test” would be treated as the same field. However, we still advise matching cases as a best practice, since there is a small portion of accounts where this change has not been made.

  

  Warning: Do not use Points as an embedded data field, as it is a reserved field in the XM Directory. Additionally, do not use any of the other Qualtrics default fields.

• Language: An optional column that identifies the contact’s language using language codes.
• Phone: An optional column that identifies the contact’s phone number. See the SMS Distributions support page for accepted phone number formats.

Qtip: If you are including these fields in your file, your column titles must perfectly match these names in capitalization and spacing. The only exception is that embedded data is not case-sensitive.

Attention: Do not change the values in the ContactID column! This field is used to identify the existing contacts. You cannot use ContactID to create new contacts. It may only be used to update existing contacts.

Date and Time Data

If you have embedded data saved in a date format, you can use a filter to search for future dates or dates that happened recently. To search by date, the date field must be in ISO-8601 format, with times in UTC. (I.e., YYYY-MM-DDT-HH:mm:ss+ZZZZ . More information about these symbols can be found on the Date Format Syntax support page).

Example: Let’s say our date is March 31, 2021 at 9:00:00AM EDT (UTC-4). This date in ISO-8601 format is 2021-03-21T13:00:00.000Z. Note how the time has been converted from EDT to UTC.

Upload a File of Directory Contacts

Make sure you start out in the Directory contacts tab.

Click Add directory contacts.

---

×

close

Click Upload a file.

---

×

close

In Excel, create a document with the required fields and save it as a CSV or TSV. Or, click Download a sample template, fill out the appropriate columns, add any desired embedded data, and save the file.

---

×

close

When the file is ready, drag and drop the file into the space provided, or click Select a file and select the file from your folder.

Click Next.

Review the rules for contact upload. Any directory-wide rules for merging duplicate contacts will show up here. These rules are set up in directory settings, and will apply to the contacts in your file.

---

×

close

Qtip: Access to the Directory Settings tab requires the Manage Directory permission. Talk to your Brand Administrator if you’re interested in getting access to this setting.

Review the fields in your file to make sure the information looks right. If a field has not been properly recognized, click on the field name to view a dropdown of options and select the correct field.

Qtip: If the data is not formatted correctly in the preview (e.g., bunched up instead of divided into columns), your data may not be separating (or “delimiting”) correctly. To fix this, choose a different Delimiter and/or Enclosure.

---

×

close

Qtip: If a contact is uploaded with an empty embedded field that already has a value stored in that field, whether or not that field is overwritten or left the same is dependent on directory settings.

Qtip: Qualtrics will flag import fields that are similar to embedded data fields in the directory to prevent creating unnecessary duplicate fields. Fields are flagged based on spelling or meaning. For example, if the import file includes a field labeled “Zip”, it will be flagged as similar to an existing directory field labeled “Zip Code”.

Click Upload the file to upload the contacts to your directory.

Qtip: Excel interprets non-ASCII characters (e.g., 是 or ñ) in a unique fashion that makes them difficult for Qualtrics to upload. If you are importing names with special characters, you might need to save your contact list info to a text-editor application (e.g., Text-edit for Mac, Notepad for PC) before you upload the file into Qualtrics. See the Special Character Issues on our CSV/TSV Upload Issues page for additional instructions.

Troubleshooting Contact File Imports

Qualtrics makes it easy to check on the status of your contact imports and fix any errors that may have occurred. During the upload process, you might receive a notice if your file is set up incorrectly. You’ll be given a solution and prevented from uploading the file until it’s fixed, keeping your directory data clean and accurate.

Example: In the screenshot below, the file was blocked because one of the values was over 20 characters. This gives us an idea of what to look for when we correct our file.

---

×

close

Downloading an Import’s Status Report

We provide a line by line file of each contact and information about whether it was imported correctly. This serves as a reference so that if your contacts fail to import, you can identify what the issue was, fix the file, and try again.

After uploading your file, click the Tasks completed button.

---

×

close

Qtip: If importing contacts to a specific mailing list, you can click the toolbox from inside the mailing list, too.

Click View import details.

Review the summary of the import. This will include how many contacts were created, how many contacts were updated, and how many contacts failed to import. Additionally, your import will be assigned a Progress ID, which is useful to have on hand if you need to contact Qualtrics Support.

---

×

close

To download your error report file, click Download a report.

Qtip: Depending on the size of your upload, it may take a few moments for the report to generate.

Open the file in a spreadsheet editor on your computer, and review the file for any contacts that failed. The column most useful for identifying failed contacts is the ImportStatus column. More information about each column is below.

Below is a description of each field in the error report:

• SourceIndexId: The index, or row ID, of the contact in the import file.
• Email: The email address associated with the contact.
• ContactId: The ID of the contact in your directory.
• ImportStatus: The import status for the contact. Values include: Added, Updated, and Failed.
• ImportStatusCode: The status code for the import. See the next section for a list of codes and their meanings.
• TransactionId: If applicable, the Transaction ID of the contact upload or update.

  

  Qtip: You can set up transactions when using a contact import workflow, or when adding contacts via API.

• TransactionStatus: If applicable, the status for the transaction. Values include: Added, Updated, and Failed.
• TransactionStatusCode: The status code for the transaction. See the next section for a list of codes and their meanings.
• ContactListContactId: If adding contacts to a mailing list or creating a new list, the ID of the contact in the specific mailing list.
• ContactListContactStatus: If adding contacts to a mailing list or creating a new list, the status of the addition or update. Values include: Added, Updated, and Failed.
• ContactListContactStatusCode: The status code for the contact in the mailing list. See the next section for a list of codes and their meanings.

Common File Errors and Their Status Codes

Below is a list of possible status codes and their descriptions.

Qtip: If contacting support for help, have your troubleshooting file handy.

Other Troubleshooting Tips

• Header spelling: Make sure you have all of the relevant headers. Capitalization, spelling, and spacing do matter. See a list of default fields.
• Missing headers: All columns must have headers.
• Character limits: Your file may have a field or multiple fields that exceed the character limit. Review the character limits below:
  • Language: 20
  • First name: 100
  • Last name: 100
  • Email address: 254
  • Phone number: 20
  • External data reference: 100
  • Embedded data field: 200
  • Embedded data value: 1,024
• Blank values: Keep in mind that directory settings can affect how blank values are treated. If you’re trying to update a contact and don’t get the result you expect, that may be due to a setting an admin configured. See Importing Blank Values in XM Directory.
• File Format Issues: If the tips in this section haven’t resolved your issue, see also the CSV and TSV Upload Issues page.

Manually Inputting Directory Contacts

Make sure you start out in the Directory contacts tab.

Click Add contacts.

---

×

close

Select Manual Input.

---

×

close

Review the contact upload rules. Any directory-wide rules for merging duplicate contacts will show up here. These rules are set up in directory settings, and will apply to the contacts you enter.

---

×

close

Fill out the available fields. You can type in or copy and paste contact information.

Click the plus sign (+) to add an additional column for embedded data. Remember, these can be whatever you want.

Click Next to upload your contacts.

Adding Contacts from Digital Intercepts

You can automatically add contacts into your XM Directory from any digital intercepts you may have created. More information on how to set up automatic contact creation in Website / App Feedback projects can be found on the XM Directory Integration with Digital Intercepts support page.

Automatically Pulling Contacts from Another Platform

You can set it up so that contacts are automatically pulled from another service you use (such as an SFTP, Qualtrics File Service, Google Drive, or more) into Qualtrics. Choose the schedule that works best for you and your team, then leave it to run on its own.

See this XM Directory Workflows page for more information.