Loading...
  • Customer Experience
    Customer Experience
  • Employee Experience
    Employee Experience
  • Brand Experience
    Brand Experience
  • Product Experience
    Product Experience
  • Core XM
    Core XM
  • Design XM
    Design XM

Adding Directory Contacts

What's on This Page:


Was this helpful?


This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!


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 directory contacts button.

Add Directory Contacts button in the upper-right of the Directory Contacts tab

Qtip: Contacts added to the directory are visible to every user in the brand.
Qtip: Before adding any new contacts, be sure to check out your settings for consolidating duplicates, which you can find in the Directory Settings tab. These settings determine how duplicates are identified and combined.

Available 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.

A CSV with all the columns listed below

Qtip: Depending on how your directory consolidates 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 consolidate 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 consolidates 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 since 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 embedded data.
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.

Upload a File

  1. Click Add directory contacts.
    Add Directory Contacts button in the upper-right of the Directory Contacts tab
  2. Click Upload a File.
    Upload file option on the left of the Add Contacts window
  3. 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.
    New window opens - small text linking to example doc, then a big box where you can drag and drop files or click to browse
  4. 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.
  5. Review the Verify Fields section 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.
    Verify Fields section featuring a preview of the uploaded contacts

    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, select the blue Show Options link and choose a different Delimiter and/or Enclosure.

    Delimiter and enclosure fields

  6. Click Upload the file to upload them 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 File Imports

Qualtrics makes it easy to check on the status of your contact imports and fix any errors that may have occurred. 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.

To get a detailed status of your import:

  1. After uploading your file, click the toolbox icon in the top-right corner of the Directory Contacts tab.
    clicking the toolbox and then view import status

    Qtip: If importing contacts to a specific mailing list, you can click the toolbox from inside the mailing list, too.
  2. Click View import details.
  3. 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.
    the summary screen with the download report button
  4. 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.
  5. 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.

Error Report Fields

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 automation, 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.

Status Codes

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

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

Status Code Description
0 An unknown error occurred; please contact Qualtrics for support.
1 An unknown error occurred; please contact Qualtrics for support.
10 The contact FirstName is empty or invalid; please enter a valid first name.
11 The contact LastName is empty or invalid; please enter a valid last name.
12 The contact value for ExternalDataReference is empty or invalid; please enter a valid ExternalDataReference value.
13 The contact Phone is empty or invalid; please enter a valid phone number.
14 The contact Email is empty or invalid; please enter a valid email address.
40 The contact was created successfully.
41 The contact was updated successfully.
42 The contact wasn’t created; please contact Qualtrics for support.
43  The contact wasn’t created; please contact Qualtrics for support.
44  The contact wasn’t created; please contact Qualtrics for support.
45  The contact wasn’t created; please contact Qualtrics for support.
46  The contact wasn’t created; please contact Qualtrics for support.
47  The contact wasn’t created; please contact Qualtrics for support.
60 The contact was added to the mailing list successfully.
61 The contact was updated in the mailing list successfully.
62 The contact wasn’t added to the mailing list; please contact Qualtrics for support.
70 The transaction was created successfully.
71 The transaction import failed – there was no valid contact associated with the transaction; please provide valid contact information.
72 The transaction wasn’t created; please contact Qualtrics for support.
73 The transaction creation failed because ContactId or ContactListContactId wasn’t found in the directory; please enter a valid ContactId and ContactListContactId.
74 The transaction creation failed due to missing TransactionDate; please enter a valid transaction date.
75 An unknown error occurred; please contact Qualtrics for support.
76 An unknown error occurred; please contact Qualtrics for support.
77 The values for ContactID, MailingListID, or TransactionDate are empty or invalid; please enter a valid ContactID, MailingListID, and TransactionDate.
78 The transaction wasn’t created because the associated contact creation failed; please contact Qualtrics for support.

Manual Input

  1. Click Add Directory Contacts.
    Add Directory Contacts button in the upper-right of the Directory Contacts tab
  2. Select Manual Input.
    On the Add Contacts window the Manual Input option is on the right
  3. Fill out the available fields.
    Contacts fields filled out
  4. Click the plus sign (+) to add an additional column for embedded data. Remember, these can be whatever you want.
  5. To finish, click Add Contacts.
    Add Contacts window with Add Contacts button in green on the lower-right

FAQs