Managing Contacts in Mailing Lists for XM Directory

This guide contains information about using the APIs for managing contacts in mailing lists for XM Directory. For information on managing mailing lists themselves, see Managing Mailing Lists for XM Directory.

XM Directory and XM directory Lite Only

These APIs are only available to XM Directory users.

This guide covers the following APIs:

Create Contact in Mailing List
List Contacts in Mailing List
Get Contact in Mailing List
Update Contact in Mailing List
Get Contact History for Mailing List Contact
Delete Contact in Mailing List

Code and Qualtrics Support

Our support team does not offer assistance or consultation on custom coding, but you can always try asking our community of dedicated users. If you’d like to know more about our custom coding services you can commission, please contact your Qualtrics Account Executive.

Create Contact in Mailing List

This API allows you to create a new contact in the specified mailing list. This API is the only way to add a contact to a mailing list; there is not a way to reuse a contact from the organization's contacts directory in a mailing list.

When you use this API, the contact you create is also created in the organization's contacts directory. This means that if the contact already exists in the organization's contacts directory, a duplicate will be created. You can then use XM Directory's de-duplication tool to remove these duplicate contacts. See Manage Directory Duplicates for more information.

# Create Contact in Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_1234567"
mailingListId = "CG_34567890"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts".format(dataCenter, directoryId, mailingListId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = {"firstName": "James",
  "lastName": "Smith",
  "email": "js@example.com",
  "phone": "8005552000",
  "embeddedData": { "level": "mid", "area": "coast" },
  "language": "en",
  "extRef": "1234567",
  "unsubscribed": True,
   }
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)

The following response object shows a typical result from this API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "641ca8da-fb07-4319-907b-ab45af1a93c2"
    },
    "result": {
        "id": "CID_123456"
    }
}

List Contacts in Mailing List

The List Contacts API returns all of the contacts in the specified mailing list. The information on each contact includes:

The contact's ID
The email address
The external reference (user-defined data attached to a contact)
The contact's first name
The contact's last name
The language (if specified)
The phone number
Whether the contact has unsubscribed ("opted-out") of the specified mailing list

# List Contacts in Mailing List

import requests

# Setting user Parameters

apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_123456"
mailingListId = "CG_123456"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts".format(dataCenter, directoryId, mailingListId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following shows an example response returned from this API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "7de14d38-f5ed-49d0-9ff0-773e12b896b8"
    },
    "result": {
        "elements": [
            {
                "contactId": "CID_123456",
                "email": "js@example.com",
                "extRef": "1234567",
                "firstName": "James",
                "language": "en",
                "lastName": "Smith",
                "phone": "8005552000",
                "unsubscribed": false
            },
            {
                "contactId": "CID_3456789",
                "email": "person@example.com",
                "extRef": "12345678",
                "firstName": "John",
                "language": "en",
                "lastName": "Smith",
                "phone": "8005551212",
                "unsubscribed": true
            }
        ],
        "nextPage": null
    }
}

Get Contact in Mailing List

The Get Contact in Mailing List API returns information about the specified contact in the specified mailing list. The information is almost identical to the information returned by the Get Contact API, with two differences:

This API does not return mailing list membership information.
This API returns an ID that uniquely identifies the contact in this mailing list (contactLookupId).

The following sample shows how to use the Get Contact in Mailing List API:

# Get Contact in Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_1234567"
mailingListId = "CG_12345"
contactId = "CID_1234567"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}".format(dataCenter, directoryId, mailingListId, contactId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following shows an example of the response that this endpoint returns:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "7684ed69-832d-4f91-899d-d6c8aa7ccea2"
    },
    "result": {
        "contactId": "CID_1234567",
        "contactLookupId": "CGC_12345",
        "creationDate": 1500667426000,
        "directoryUnsubscribeDate": null,
        "directoryUnsubscribed": false,
        "email": "js@example.com",
        "emailDomain": null,
        "embeddedData": {
            "area": "coast",
            "level": "mid"
        },
        "extRef": "1234567",
        "firstName": "James",
        "language": "en",
        "lastModified": 1500667426000,
        "lastName": "Smith",
        "mailingListUnsubscribeDate": null,
        "mailingListUnsubscribed": false,
        "phone": "8005552000",
        "stats": {
            "AvgTimeToRespond": "0.0",
            "DataIntegrity": "100",
            "EmailCount": "1",
            "InviteCount": "1",
            "LastEmailDate": "2017-07-25 21:00:31",
            "LastInviteDate": "2017-07-25 21:00:31",
            "LastResponseDate": "2017-07-25 21:02:19",
            "MonthEmailCount": "1",
            "MonthInviteCount": "1",
            "Points": "0",
            "ResponseCount": "1",
            "ResponseRate": "1.0"
        },
        "writeBlanks": false
    }
}

The result contains the following data:

Member	Type	Description
contactId	String	The contact ID.
contactLookupId	String	The contact lookup ID
creationDate	Number	Date and time this contact's record was created. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
directoryUnsubscribeDate	Number	Date and time the user opted out of the directory. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
directoryUnsubscribed	Boolean	Indicates whether the user opted out of the directory.
email	String	The contact's email address.
emailDomain	String	The contact's email domain.
embeddedData	Object	The embedded data object contains extra metadata that you want to associate with contacts. This user-defined data could include such data as birthplace, gender, employment status, etc. See Update Contact below for an example of setting the embedded data object.
extRef	String	External reference. You can place any string data here that you need to attach to a contact.
firstName	String	The contact's first name or given name.
language	String	The contact's language if set.
lastModified	Number	Date and time this record was last modified. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
lastName	String	The contact's last name or surname.
mailingListUnsubscribeDate	Number	Date and time the user opted out of this mailing list. Expressed in milliseconds since the Unix epoch, January 1, 1970 at 0:00 UTC.
mailingListUnsubscribed	Boolean	Whether the user has opted out of receiving email through this mailing list.
phone	String	The contact's phone number.
stats	Object	The stats object for the contact. See the next section for information about this object.
writeBlanks	Boolean	Whether to write blanks.

The stats object

The stats object contains information about interactions with this contact.

Mailing list contact stats equivalent to directory contact's stats

The stats object documented here does not contain statistical information specific to the specified mailing list. Instead, it contains the same information as the stats object returned from the Get Contact API.

The information contained in the stats object appears in the following table:

Member	Type	Description
AvgTimeToRespond	String	Average time, in hours, that passed before the contact started taking a survey after the invitation was sent.
DataIntegrity	String	The contact's data integrity score. 100 is the highest score.
EmailCount	String	Number of emails sent to this contact since the contact was created.
InviteCount	String	Number of invitations to take surveys that have been sent to this contact since the contact was created.
LastEmailDate	String	Timestamp of last Qualtrics distribution event (including survey invitations, general emails, reminders, site intercepts, and thank you messages). The date and time is in UTC formatted as yyyy-MM-dd HH:mm:ss.
LastInviteDate	String	Timestamp of last survey invitation that was sent via Qualtrics. The date and time is in UTC formatted as yyyy-MM-dd HH:mm:ss.
LastResponseDate	String	Last date and time this contact completed a survey. The date and time is in UTC formatted as yyyy-MM-dd HH:mm:ss.
MonthEmailCount	String	The number of emails sent to this contact in the month that the API was called.
MonthInviteCount	String	The number of invitations to take surveys sent to this contact in the month that the API was called.
Points	String	The number of incentive points this contact has earned.
ResponseCount	String	Number of surveys in total that this contact completed since the contact was created.
ResponseRate	String	The ratio of surveys this contact completed compared to the total number of surveys sent. The number ranges from 0.0 to 1.0.

Update Contact in Mailing List

The Update Contact in Mailing List API allows you to change data associated with a contact.

The functionality provided by this API is also provided by the Update Contact API. The Update Contact API, however, does not require a mailing list ID.

# Update Contact in Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_1234"
mailingListId = "CG_5678"
contactId = "CID_3421"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}".format(dataCenter, directoryId, mailingListId, contactId)
headers = {
    "x-api-token": apiToken,
    "Content-Type": "application/json"
    }

data = {"firstName": "John",
  "lastName": "Smith",
  "email": "person@example.com",
  "phone": "8005551212",
  "embeddedData": { "birthplace": "San Francisco, CA", "gender": "M" },
  "language": "en",
  "extRef": "12345678",
  "unsubscribed": True
   }
response = requests.put(baseUrl, json=data, headers=headers)
print(response.text)

The following response shows a successful result from this API:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "2b88e3d5-4c8f-4896-ad8a-f4a2f08b41d3"
    }
}

Get Contact History for Mailing List Contact

The Get Contact History API returns information about either the email sent to a contact or the survey responses supplied by a contact. The type query parameter specifies the type of history that should be returned. The following code example demonstrates how to return a contact's survey response history (type is set to response).

# Get Contact History

import os
import requests

# Setting user Parameters
apiToken = os.environ["Q_API_TOKEN"]
dataCenter = os.environ["Q_DATA_CENTER"]
directoryId = os.environ["Q_TA_POOL_ID"]
mailingListId = os.environ["Q_TA_MAILINGLIST_ID"]

contactId = "CID_6h4Y4JDg2zXYYzX"

type = "response" # Either "email" or "response"

baseUrl = "https://{0}./directories/{1}/mailinglists/{2}/contacts/{3}/history?type={4}".format(dataCenter, directoryId, mailingListId, contactId, type)
headers = {
    "x-api-token": apiToken,
    }

response = requests.get(baseUrl, headers=headers)
print(response.text)

The following response object shows the contact's email history (with type set to email):

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "12cb2e5c-f00d-4f2a-a08e-1a55c385a095"
    },
    "result": {
        "elements": [
            {
                "date": "2017-08-08 14:45:19",
                "distributionId": "EMD_5vdjLiUJT1JATop",
                "read": true,
                "result": "Success",
                "surveyId": "SV_cBjbWZ2uyPIQVLf",
                "type": "Invite"
            },
            {
                "date": "2017-08-08 14:48:29",
                "distributionId": "EMD_ensZ9RWVGGV8vt3",
                "read": true,
                "result": "Success",
                "surveyId": "SV_cBjbWZ2uyPIQVLf",
                "type": "Reminder"
            },
            {
                "date": "2017-08-08 16:10:06",
                "distributionId": "EMD_4NQJnBmJpTlQDqt",
                "read": false,
                "result": "Success",
                "surveyId": "SV_cBjbWZ2uyPIQVLf",
                "type": "ThankYou"
            },
            {
                "date": "2017-08-16 20:21:25",
                "distributionId": "EMD_0Ui5Rn6xp3BrWbH",
                "read": false,
                "result": "Success",
                "surveyId": "SV_8pivLTQNqPohG5v",
                "type": "Invite"
            },
            {
                "date": "2017-09-04 19:47:31",
                "distributionId": "EMD_4JBtumqDmrpzkhf",
                "read": false,
                "result": "Blocked",
                "surveyId": "SV_9ukvzzzAdLsjLq5",
                "type": "Invite"
            },
        ],
        "nextPage": null
    }
}

Delete Contact in Mailing List

The Delete Contact in Mailing List API removes the specified contact from the specified mailing list. It does not remove the contact from the organization's contact directory even if the contact appears on no other mailing list.

# Delete Contact in Mailing List

import requests

# Setting user Parameters
apiToken = "YOUR API TOKEN"
dataCenter = "YOUR DATACENTER"

directoryId = "POOL_123456"
contactId = "CID_1234"
mailingListId = "CG_1234567"

baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}".format(dataCenter, directoryId, mailingListId, contactId)
headers = {
    "x-api-token": apiToken,
    }

response = requests.delete(baseUrl, headers=headers)
print(response.text)

The following response object shows the result of a successful delete:

{
    "meta": {
        "httpStatus": "200 - OK",
        "requestId": "ed27363d-9043-4c03-b965-aba4d331cbd8"
    }
}

If you attempt to delete a contact which has already been deleted it will return a 404 to indicate that this contact does not exist.

{
  "meta": {
    "httpStatus": "404 - Not Found",
    "error": {
      "errorMessage": "Contact does not exist"
    }
  }
}

XM Directory and XM directory Lite Only​

Code and Qualtrics Support​

Create Contact in Mailing List​

List Contacts in Mailing List​

Get Contact in Mailing List​

The stats object​

Mailing list contact stats equivalent to directory contact's stats​

Update Contact in Mailing List​

Get Contact History for Mailing List Contact​

Delete Contact in Mailing List​

XM Directory and XM directory Lite Only

Code and Qualtrics Support