Changes to XMD Public API

What are the changes?

Qualtrics is committed to providing the best experience for our customers. In an effort to ensure a reliable experience for all of our customers, we are planning the following changes:

Change 1: The response body to the below API calls will no longer return the contactCount field by default. In order to receive this field in the API response the API caller will need to include the includeCount query parameter and set the value to True.

Calls Impacted

GET /API/v3/directories

GET /API/v3/directories/:directoryId/mailinglists

GET /API/v3/directories/:directoryId/mailinglists/:mailinglistId

Example output from GET /API/v3/directories (note the parameter contactCount will be removed)

   "elements": [
     {
       "directoryId": "POOL_012345678901234",
       "name": "string",
       "contactCount": 0,
       "isDefault": true,
          .
          .
          .
       }
     }

Change 2: Qualtrics is going to remove some fields that have been deprecated and are no longer used in the Qualtrics schema from the following API calls. GET /directories/:directoryId/contacts/:contactId

Will remove the following fields from the request response: writeBlanks, transactionData, DataIntegrity, Points

{
 "result": {
   "contactId": "CID_012345678901234",
   "creationDate": "string",
   "writeBlanks": true,
   "transactionData": [
     {}
   ],
       .
       .
       .
 },

GET /directories/:directoryId/mailinglists/:mailinglistId/contacts/:contactId Will remove the following fields: writeBlanks,DataIntegrity,Points

{
 "result": {
   "contactId": "CID_012345678901234",
   "creationDate": "string",
   "writeBlanks": true,
       .
       .
       .
 },

Change 3: Qualtrics found a bug where some contacts were not setting an unsubscribedDate when they were opted-out. This was causing issues with the List Opted Out Directory Contacts API call, causing the API call to incorrectly not return these contacts. To correct this issue, the default value of the since parameter on the GET /directories/:directoryId/contacts/optedOutContacts will be changed from 2008-01-02T00:00:00Z to null, which will correct the calculation and this call will now return these previously filtered contacts.

What actions do I need to take?

Please be aware that all of these changes will take place on June 7, 2022, please make any required changes to your code prior to this date.

Change 1: If your calls to the above endpoints do not rely on the contactCount field, there is no action required.

If you have calls to the above endpoints and rely on the contactCount field in the response, you will need to set the includeCount query parameter to true to continue to receive this parameter:

https://<insertCorrectDataCenter>.qualtrics.com/API/v3/directories?includeCount=True

Change 2: If your calls to the above endpoints do not rely on these fields being removed there is no action required. Otherwise, please remove any logic that you have based on these fields being returned in Public API responses.

Change 3: If your API call was previously relying on the default value of opt-out since parameter to be 2008-01-02T00:00:00Z then please specify this value explicitly. If you were expecting to fetch all opt-out contacts from the past, then no action is required.

What if I have questions?

If you have a question about the XMD API changes, please visit the Public API documentation site. It’s also always worth checking the XM Community to see if any other users have the same question. If you’d rather speak to a specialist, our Support Team is always ready to assist. To contact them, please log into your Support Portal.