Managing Directory Contacts for XM Directory
XM Directory users can use the APIs mentioned in the following guide to manage the organization's directory, which contains all of an organization's contacts.
All of the following APIs require the XM Directory directory ID (also known as a pool ID) and an account authorized for XM Directory. The directory's ID is available in the XM Directory user interface under Account Settings and Qualtrics IDs. See Finding Your Qualtrics IDs.
XM Directory Only
These APIs are only available to XM Directory users.
This guide contains information on the following APIs:
Create Contact
The Create Contact API allows you to create new contacts in the XM Directory directory. You can create a contact with the following metadata:
- First name
- Last name
- Email address
- Phone number
- Language
- External Data Reference
- Unsubscribed
In addition, you can create any metadata you want and attach it to the embeddedData object as the example below shows:
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
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"]
baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts".format(dataCenter, directoryId)
headers = {
"x-api-token": apiToken,
"Content-Type": "application/json"
}
data = {
"firstName": "John",
"lastName": "Smith",
"email": "person@example.com",
"phone": "8005551212",
"language": "en",
"embeddedData": { "level": "mid", "area": "coast" },
"unsubscribed": false,
"extRef": "my external data"
}
response = requests.post(baseUrl, json=data, headers=headers)
print(response.text)
This will receive a response like:
{
"result": {
"id": "CID_012345678901234"
},
"meta": {
"httpStatus": "200 - OK",
"requestId": "900df19-75fd-479d-b4c2-6fd1f4b7b3e0"
}
}
List Contacts
The List Contacts API lists the current contents of the XM Directory directory. Because the collection is often large, you will probably need to paginate through the data. You can either use the pageSize and offset parameters to specify what page of the collection you'd like to view, or you can repeatedly call this API using the nextPage value in the results object to obtain the next page until nextPage is null.
Embedded Data
The List Contacts API does not return the embedded data for each contact. You need to call Get Contact on each contact for which you wish to obtain their embedded data.
The following example shows how to use the List Contacts API with a specific offset and page size:
# List Contacts
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"]
pageSize = 100
offset = 0
baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts?pageSize={2}&offset={3}".format(dataCenter, directoryId, pageSize, offset)
headers = {
"x-api-token": apiToken,
}
response = requests.get(baseUrl, headers=headers)
print(response.text)
This will receive a response like
{
"result": {
"elements": [
{
"contactId": "CID_012345678901234",
"firstName": "exampleFirstName0",
"lastName": "exampleLastName0",
"email": "example0@example.com",
"phone": "0000000000",
"extRef": "reference.com",
"language": "es",
"unsubscribed": false
},
{
"contactId": "CID_012345678901235",
"firstName": "exampleFirstName1",
"lastName": "exampleLastName1",
"email": "example1@example.com",
"extRef": "reference.com",
"phone": null,
"language": "de",
"unsubscribed": true
}
]
}
}
Get Contact
The Get Contact API returns extensive information about the specified contact. The information includes metadata about the contact (such as first name), embedded data, and statistics about the contact's survey responses and email interactions.
# Get Contact
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"]
contactId = "CID_12345"
baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}".format(dataCenter, directoryId, contactId)
headers = {
"x-api-token": apiToken,
}
response = requests.get(baseUrl, headers=headers)
print(response.text)
{
"meta": {
"httpStatus": "200 - OK",
"requestId": "bf10764c-3f2b-4bf2-8098-7be1badf7b9c"
},
"result": {
"contactId": "CID_eJa3wtJLn2R0gBf",
"creationDate": 1498679121000,
"directoryUnsubscribeDate": 1498846923000,
"directoryUnsubscribed": true,
"email": "person@example.com",
"emailDomain": null,
"embeddedData": {},
"extRef": null,
"firstName": "John",
"language": "en",
"lastModified": 1498679121000,
"lastName": "Smith",
"mailingListMembership": {
"CG_6tDFg6cUKfhiitD": {
"contactLookupId": "CGC_0kOdwqXN7OTydx3",
"name": "EL",
"ownerId": "UR_12345678",
"unsubscribeDate": null,
"unsubscribed": false
},
"CG_eJLNberNOVbGhRX": {
"contactLookupId": "CGC_3h4eh3L4bv7FCcd",
"name": "TA",
"ownerId": "UR_12345678",
"unsubscribeDate": null,
"unsubscribed": false
}
},
"phone": "8005551212",
"stats": {
"AvgTimeToRespond": "0.0",
"DataIntegrity": "100",
"EmailCount": "2",
"InviteCount": "1",
"LastEmailDate": "2017-06-29 21:03:35",
"LastInviteDate": "2017-06-29 19:58:45",
"LastResponseDate": "2017-06-29 20:02:20",
"MonthEmailCount": "2",
"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. |
| 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. |
| 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. |
| mailingListMembership | Object | An object that represents the mailing lists that this contact belongs to. See "Mailing List Membership" below for more information. |
| 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 as shown 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. |
Mailing list membership
The mailingListMembership object contains information about the mailing lists this contact belongs to. The object contains objects for each mailing list. For example, this contact belongs to two mailing lists identified with CG_12345667 and CG_567890:
"mailingListMembership": {
"CG_12345667": {
"contactLookupId": "CGC_cPkqDdd1hSpzP9z",
"name": "EL",
"ownerId": "UR_12345678",
"unsubscribeDate": null,
"unsubscribed": false
},
"CG_567890": {
"contactLookupId": "CGC_bOBAmLhCg6wUATP",
"name": "TA",
"ownerId": "UR_12345678",
"unsubscribeDate": null,
"unsubscribed": false
}
},
Each mailingListMembership object contains the following:
| Member | Type | Description |
|---|---|---|
| contactLookupId | String | The contact's unique ID in the mailing list. |
| name | String | The name of the mailing list. |
| ownerId | String | The ID of the user who owns the mailing list. |
| unsubscribeDate | String | The date the contact opted out of this mailing list. Is set to null if the user has not opted out. |
| unsubscribed | Boolean | Whether the contact opted out of the mailing list. |
Get Contact History
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"]
contactId = "CID_6h4Y4JDg2zXYYzX"
type = "response" # Either "email" or "response"
baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}/history?type={3}".format(dataCenter, directoryId, 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):
{
"elements": [
{
"distributionId": "EMD_1234567890abcde",
"date": "2015-04-09 19:42:29",
"type": "Invite",
"result": "Success",
"surveyId": "SV_1234567890abcde",
"read": true
},
{
"distributionId": "EMD_1234567890abcdf",
"date": "2015-04-09 19:42:29",
"type": "Invite",
"result": "Bounce",
"bounceInfo": {
"type": "Hard"
},
"surveyId": "SV_1234567890abcde",
"read": false
}
],
"nextPage": null
},
"meta": {
"httpStatus": "200 - OK"
}
}
The elements array contains objects that are described in the following table:
| Member | Type | Description |
|---|---|---|
| date | String | UTC time of the distribution event in yyyy-MM-dd HH:mm:ss format. |
| distributionId | String | The distribution's ID, which can be used with Get Distribution to obtain more information about the distribution. |
| read | Boolean | Indicates whether the distribution email has been read. |
| result | String | Indicates whether the email was delivered (Success), bounced (Blocked) |
| bounceInfo | Object | An object that indicates the type of bounce as a string |
| surveyId | String | The survey ID of the survey referenced by this distribution. |
| type | String | The type of email distribution. Either Invite, ThankYou, or Reminder. |
The following response object shows the contact's response history (when type is set to response):
{
"meta": {
"httpStatus": "200 - OK",
"requestId": "607a5061-6ba7-4014-875d-7da1315c61a2"
},
"result": {
"elements": [
{
"distributionId": "EMD_5vdjLiUJT1JATop",
"responseId": "R_qFxoeiLscvMneff",
"surveyCompletedDate": "2017-08-08 14:58:57",
"surveyFinished": true,
"surveyId": "SV_cBjbWZ2uyPIQVLf",
"surveyStartedDate": "2017-08-08 14:58:53"
},
{
"distributionId": "EMD_9odFkKG1Cdflln7",
"responseId": "R_2wvOxMidyyh7ZKb",
"surveyCompletedDate": "2017-08-17 20:52:29",
"surveyFinished": true,
"surveyId": "SV_8pivLTQNqPohG5v",
"surveyStartedDate": "2017-08-17 20:52:18"
},
{
"distributionId": "EMD_eanPyQa5ondBhkN",
"responseId": "R_rfjAlFwK65ZsNYR",
"surveyCompletedDate": "2017-08-17 22:32:27",
"surveyFinished": true,
"surveyId": "SV_6hZDPZroTErKGZD",
"surveyStartedDate": "2017-08-17 22:32:16"
},
{
"distributionId": "EMD_eXog2zBKVo9Fpnn",
"responseId": "R_b8vRD49BdnI4Pct",
"surveyCompletedDate": "2017-09-04 19:36:57",
"surveyFinished": true,
"surveyId": "SV_9ukvzzzAdLsjLq5",
"surveyStartedDate": "2017-09-04 19:36:43"
},
{
"distributionId": null,
"responseId": "R_1eM2NjAkNoH08mx",
"surveyCompletedDate": "2017-09-04 19:55:47",
"surveyFinished": true,
"surveyId": "SV_9ukvzzzAdLsjLq5",
"surveyStartedDate": "2017-09-04 19:55:48"
}
],
"nextPage": null
}
}
The following table provides information on the objects in the elements array:
| Member | Type | Description |
|---|---|---|
| distributionId | String | The email distribution ID associated with the response. This ID can be used with Get Distribution to obtain more information about the distribution. |
| responseId | String | The contact's response ID. Indicates the contact's response to the survey. |
| surveyCompletedDate | String | The date and time in UTC in the format yyyy-MM-dd HH:mm:ss that the contact completed the survey. |
| surveyFinished | Boolean | Whether this contact finished the survey. |
| surveyId | String | The survey's ID. |
| surveyStartedDate | String | The date and time in UTC in the format yyyy-MM-dd HH:mm:ss that the contact started the survey. |
Update Contact
The Update Contact API allows you to change existing metadata for a contact. You can also add or update a contact's embedded data.
The example below shows how to update a contact's information and change or add embedded data:
# Update Contact
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"]
contactId = "CID_1234567"
baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}".format(dataCenter, directoryId, 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)
This will receive a response like:
{
"meta": {
"httpStatus": "200 - OK",
"requestId": "900df19-75fd-479d-b4c2-6fd1f4b7b3e0"
}
}
Delete Contact
The Delete Contact API allows you to permanently delete a contact from the organization's directory. The example below shows how to use this API:
# Delete Contact
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"]
contactId = "CID_123456789"
baseUrl = "https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}".format(dataCenter, directoryId, contactId)
headers = {
"x-api-token": apiToken,
}
response = requests.delete(baseUrl, headers=headers)
print(response.text)
A successful delete results in a 200 status code. An example response is shown below:
{
"meta": {
"httpStatus": "200 - OK",
"requestId": "1702483a-ced4-40a5-9ade-20e01475055b"
}
}