Research Core to XM Directory Migration Guide

Glossary

• Contact: A person or entity with information stored in XMD.
• Contact ID: An alphanumeric identifier for a contact. Typically starts with CID_. This ID is used in all Contact-related XMD API calls.
• Directory: A directory is a collection of contacts, each with a list of attributes describing them and their interactions with your brand.
• Directory ID: An alphanumeric identifier for a directory. Typically starts with POOL_.
• Mailing List: A subset of contacts that can receive emails and survey invitations. Unlike the directory, mailing lists are not visible to the entire organization, but are instead created in individual accounts. Mailing lists can be shared with other users or groups.
• Mailing List ID: An alphanumeric identifier for a mailing list. Typically starts with ML_ or CG_.
• Lookup ID: An alphanumeric identifier for a contact’s membership in a specific mailing list. Typically starts with MLRP_ or CGC_. This ID is primarily used in all contact-related Research Core API calls.

Contact ID Conversion

Research Core Contact APIs refer to a contact’s Lookup ID (CGC/MLRP) as the contactId. The XMD APIs refer to a contact’s Contact ID (CID) as the contactId.

If you have a database on your side that stores contact Lookup IDs and you need to find all of the associated Contact IDs, you should use the List Contacts In Mailing List XMD API to list all of the contacts in a list and find the Lookup ID and Contact ID for each contact.

API Calls

Delete Mailing List

	Research Core Contact API	XMD API
Route	/API/v3 /mailinglists/{mailingListId}	API/v3/directories/{directoryId}/mailinglists/{mailingListId}
Documentation Link	https://api.qualtrics.com/ae0d4b6f2b80a-delete-mailing-list	https://api.qualtrics.com/7b9390be797ef-delete-mailing-list

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

N/A

Get Mailing List

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}
Documentation Link	https://api.qualtrics.com/497e11cf3f89f-get-mailing-list	https://api.qualtrics.com/3bd1a82518049-get-mailing-list

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
Uses id as key	Changes to mailingListId
Uses libraryId as key	Changes to ownerId
Used category as key	The category key isn’t returned

The XMD API has additional fields in the response payload but this shouldn’t affect an API migration.

Update Mailing List

	Research Core Contact API	XMD API
Route	/API/v3 /mailinglists/{mailingListId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}
Documentation Link	https://api.qualtrics.com/18cb64657e4bf-update-mailing-list	https://api.qualtrics.com/010e23b9eaebc-update-mailing-list

Route & Query String Parameter Differences

N/A

Request Body Differences

Research Core Contact API	XMD API
Uses libraryId as key	Changes to ownerId
Used category as key	The category key must be removed

Response Body Differences

N/A

List Mailing Lists

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists	/API/v3/directories/{directoryId}/mailinglists
Documentation Link	https://api.qualtrics.com/f229ba25e3b01-list-mailing-lists	https://api.qualtrics.com/dd83f1535056c-list-mailing-lists

Route & Query String Parameter Differences

Research Core Contact API	XMD API
Allows offset as parameter	Doesn’t allow offset as parameter
Default pageSize 500	Default pageSize 100

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
Uses id as key	Changes to mailingListId
Uses libraryId as key	Changes to ownerId
Used category as key	The category key isn’t returned
Used folder as key	The folder key isn’t returned

The XMD API has additional fields in the response payload but this shouldn’t affect an API migration.

Create Mailing List

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists	/API/v3/directories/{directoryId}/mailinglists
Documentation Link	https://api.qualtrics.com/36bf961da075d-create-mailing-list	https://api.qualtrics.com/3f633e4cea6cd-create-mailing-list

Route & Query String Parameter Differences

N/A

Request Body Differences

Research Core Contact API	XMD API
Uses libraryId as key	Changes to ownerId
Used category as key	The category key must be removed

Response Body Differences

N/A

Delete Contact

	Research Core Contact API	XMD API 1	XMD API 2
Route	API/v3/mailinglists/{mailingListId}/contacts/{contactId}	/API/v3/directories/{directoryId}/contacts/{contactId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/contacts/{contactId}
Documentation Link	https://api.qualtrics.com/01114a333f2ba-delete-contact	https://api.qualtrics.com/85fd6657c6260-delete-directory-contact	https://api.qualtrics.com/4ed38798f8039-delete-contact-in-mailing-list

• XMD API 1 (Delete Directory Contact) should be used when you want to delete a contact and ensure it’s deleted from the directory/brand and not just the list. To use this API, the Manage Directory permission must be enabled.
• XMD API 2 (Delete Contact in Mailing List) should be used when you want to delete a contact from only a list and leave the contact in the directory.
• For XMD Lite brands or Lite directories, we would recommend using XMD API 1

Route & Query String Parameter Differences

Research Core Contact API	XMD API 1	XMD API 2
The contact’s Lookup ID (CGC/MLRP) can be used for contactId in the route	Only the contact’s Contact ID (CID) can be used for contactId in the route	Only the contact’s Contact ID (CID) can be used for contactId in the route

Request Body Differences

N/A

Response Body Differences

N/A

Get Contact

The Research Core Get Contact API has the job of returning a contact’s contact info and embedded data in addition to the contact’s history. This job is split across two XMD APIs:

• Get Contact In Mailing List
• Get Contact History In Mailing List

Both APIs will need to be run if all information is desired for a contact.

Get Contact In Mailing List

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contacts/{contactId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/contacts/{contactId}
Documentation Link	https://api.qualtrics.com/4670d3fbc4a61-get-contact	https://api.qualtrics.com/77113dcca09c2-get-contact-in-mailing-list

Route & Query String Parameter Differences

Research Core Contact API	XMD API
The contact’s Lookup ID (CGC/MLRP) can be used for contactId in the route	Only the contact’s Contact ID (CID) can be used for contactId in the route

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
The id key is set to the contact’s Lookup ID (CGC/MLRP) or the contact’s Contact ID (CID) depending on a non-editable setting.	The id key is set to the contact’s Contact ID (CID) and the contact’s Lookup ID is set to contactLookupId
Used externalDataReference as key	Changes to extRef
Used unsubscribed as key and was set to a string. Returns the directory subscription status.	Mailing List subscription status set to mailingListUnsubscribed and is set to a boolean. Directory subscription status set to directoryUnsubscribed and is set to a boolean.
Empty contact info is returned as the string “null”	Empty contact info is returned as null

Get Contact History In Mailing List

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contacts/{contactId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/contacts/{contactId}/history
Documentation Link	https://api.qualtrics.com/4670d3fbc4a61-get-contact	https://api.qualtrics.com/4d5d4ef365856-get-contact-history-in-mailing-list

Route & Query String Parameter Differences

Research Core Contact API	XMD API
The contact’s Lookup ID (CGC/MLRP) can be used for contactId in the route	Only the contact’s Contact ID (CID) can be used for contactId in the route
No type query string	The type query string must be set to either response or email to return that specific history.

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
responseHistory and emailHistory are returned as separate keys in the results object. Each key is set to an array of history objects.	Whether responseHistory or emailHistory is returned depends on the query parameter set. The array of history objects is always set to an elements key in the results object.
Used emailDistributionId as key	Changes to distributionId
Used finishedSurvey as key	Changes to surveyFinished
responseId key returned if set to null	responseId key NOT returned if set to null
Used date as key	Dates are now broken out and saved to surveyStartedDate and surveyCompletedDate. Fields are only returned when there’s data to return.
All history returned at once	Paginated call, follow nextPage for more results.

The XMD API has additional fields in the history object but this shouldn’t affect an API migration.

Update Contact

The Research Core Update Contact API updates the contact’s directory subscription status while the XMD Update Contact In Mailing List API updates the contact’s mailing list subscription status.

	Research Core Contact API	XMD API 1	XMD API 2
Route	/API/v3/mailinglists/{mailingListId}/contacts/{contactId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/contacts/{contactId}	/API/v3/directories/{directoryId}/contacts/{contactId}
Documentation Link	https://api.qualtrics.com/d7b8a04864c38-update-contact	https://api.qualtrics.com/d98216303e054-update-contact-in-mailing-list	https://api.qualtrics.com/e7890729357b1-update-directory-contact

• XMD API 1 (Update Contact In Mailing List) should be used if you don’t need to change the contact’s directory subscription status.
• XMD API 2 (Update Directory Contact) should be used if you need to change the contact’s directory subscription status. To use this API, the Manage Directory permission must be enabled.
• For XMD Lite brands or Lite directories, we would recommend using XMD API 1

Route & Query String Parameter Differences

Research Core Contact API	XMD API 1	XMD API 2
The contact’s Lookup ID (CGC/MLRP) can be used for contactId in the route	Only the contact’s Contact ID (CID) can be used for contactId in the route	Only the contact’s Contact ID (CID) can be used for contactId in the route

Request Body Differences

Research Core Contact API	XMD API 1	XMD API 2
Uses externalDataReference as key	Changes to extRef	Changes to extRef

Response Body Differences

N/A

List Contacts

The Research Core List Contacts API has the job of returning a contact’s contact info and embedded data in addition to the contact’s history for all the contacts in a list. This job is split across two XMD APIs:

• List Contacts In Mailing List
• Get Contact History In Mailing List

The Get Contact History In Mailing List API will need to be run for each contact returned by the List Contacts In Mailing List API. More information on how history is returned via the Get Contact HIstory In Mailing List call can be seen in the Get Contact section of this migration guide.

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contacts	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/contacts
Documentation Link	https://api.qualtrics.com/05ef128bfa876-list-contacts	https://api.qualtrics.com/af95194dd116e-list-contacts-in-mailing-list

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
The id key is set to the contact’s Lookup ID (CGC/MLRP) or the contact’s Contact ID (CID) depending on a non-editable setting.	The id key is set to the contact’s Contact ID (CID). The contactLookupId key is set to the Lookup ID (CGC/MLRP)
Used externalDataReference as key	Changes to extRef
unsubscribed set to a string	unsubscribed set to a boolean
Empty contact info is returned as the string “null”	Empty contact info is returned as null
Automatically returns embedded data	Only returns embedded data if includeEmbedded query parameter is set to true
Size of page returned is 10 contacts	Size of page returned is 50 by default
Contact history automatically returned	History not included. The Get Contact History In Mailing List API must be called to get history.

Create Contact

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contacts	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/contacts
Documentation Link	https://api.qualtrics.com/f13aeb845e7a0-create-contact	https://api.qualtrics.com/fc43c25b3f3c3-create-contact-in-mailing-list

Route & Query String Parameter Differences

N/A

Request Body Differences

Research Core Contact API	XMD API
Uses externalDataRef as key	Uses extRef as key
Embedded Data can’t be set to null	Embedded Data can be set to null

Response Body Differences

Research Core Contact API	XMD API
The id key is set to the contact’s Lookup ID (CGC/MLRP) or the contact’s Contact ID (CID) depending on a non-editable setting.	The id key is set to the contact’s Contact ID (CID). The contactLookupId key is set to the contact’s Lookup ID (CGC/MLRP)

List Samples

The Research Core List Samples API retrieves the samples for a particular mailing list while the XMD List Samples API retrieves all available samples in the directory. If you want to only look at the samples for a particular mailing list, you will need to search the response body for samples with a parentGroupId set to the mailing list ID you care about.

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/samples	/API/v3/directories/{directoryId}/samples
Documentation Link	https://api.qualtrics.com/a35585771e959-list-samples	https://api.qualtrics.com/1b6abe392d030-list-samples

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
Uses id as key	Uses sampleId as key

Get Sample

The Research Core Get Sample API has the job of returning a contact’s contact info and embedded data in addition to the contact’s history for all the contacts in a sample. This job is split across two XMD APIs:

• Get Sample Contacts
• Get Contact History In Mailing List

The Get Contact History In Mailing List API will need to be run for each contact returned by the Get Sample Contacts API. More information on how history is returned via the Get Contact HIstory In Mailing List call can be seen in the Get Contact section of this migration guide.

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/samples/{sampleId}	/API/v3/directories/{directoryId}/samples/{sampleId}/contacts
Documentation Link	https://api.qualtrics.com/4de42a2f3da05-get-sample	https://api.qualtrics.com/f7b8d90819090-get-sample-contacts

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
The id key is set to the contact’s Lookup ID (CGC/MLRP)	The contactId key is set to the contact’s Contact ID (CID)
Used externalDataReference as key	Changes to extRef
unsubscribed set to a string	unsubscribed set to a boolean
Empty contact info is returned as the string “null”	Empty contact info is returned as null
Automatically returns embedded data	Only returns embedded data if includeEmbedded query parameter is set to true
Size of page returned is 10 contacts	Size of page returned is 50 by default
Contact history automatically returned	History not included. The Get Contact History In Mailing List API must be called to get history.

Create Contacts Import

The Create Contacts Import can be used in three ways:

1. The contacts object can be added to the raw data of the request
2. The contacts object can be added to a local JSON file and appended to the data of the request
3. The contacts object can be added to a remote JSON file and appended to the data of the request

The first method will continue to be supported and a migration guide can be seen below. Methods two and three will not be supported and you will either need to add the JSON to the request directly or pivot to using a CSV file and importing the file via Workflows.

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contactimports	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/transactioncontacts
Documentation Link	https://api.qualtrics.com/bb66aef20d8bc-create-contacts-import	https://api.qualtrics.com/bab13356ac724-create-transaction-contacts-import

Route & Query String Parameter Differences

N/A

Request Body Differences

Research Core Contact API	XMD API
Uses externalReference or extRef as key	Uses extRef as key
unsubscribed set to a number or string (0,1)	unsubscribed set to a boolean
JSON Content Limits: 5 MB 8,500 contacts	JSON Content Limits: 5 MB 10,000 contacts

Response Body Differences

Research Core Contact API	XMD API
meta.httpStatus is set to 200 - OK	meta.httpStatus is set to 202 - Accepted

Get Contacts Import Progress

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contactimports/{contactImportId}	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/transactioncontacts/{importId}
Documentation Link	https://api.qualtrics.com/c5e6aafeff313-get-contacts-import-progress	https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
meta.httpStatus is set to 200 - OK when a successful call is made	meta.httpStatus is set to 202 - Accepted when a successful call is made
When an incorrect importId is used: meta.httpStatus is set to 404 - Not Found error.errorMessage is set to Cannot find the given resource error.errorCode is set to BRE_0.4	When an incorrect importId is used: meta.httpStatus is set to 400 - Bad Request error.errorMessage is set to No transaction contacts import found for the directoryId, mailingListId, or progressId provided. error.errorCode is set to TCI_0.0

Get Contacts Import Progress Summary

	Research Core Contact API	XMD API
Route	/API/v3/mailinglists/{mailingListId}/contactimports/{contactImportId}/summary	/API/v3/directories/{directoryId}/mailinglists/{mailingListId}/transactioncontacts/{importId}
Documentation Link	https://api.qualtrics.com/f47279ac670c8-get-contacts-import-progress-summary	https://api.qualtrics.com/c5d22705b1d45-get-transaction-contacts-import-status

Route & Query String Parameter Differences

N/A

Request Body Differences

N/A

Response Body Differences

Research Core Contact API	XMD API
When an incorrect importId is used: meta.httpStatus is set to 404 - Not Found error.errorMessage is set to Cannot find the given resource error.errorCode is set to BRE_0.4	When an incorrect importId is used: meta.httpStatus is set to 400 - Bad Request error.errorMessage is set to No transaction contacts import found for the directoryId, mailingListId, or progressId provided. error.errorCode is set to TCI_0.0

Get Transaction Contacts Import Summary

The information provided in this API is already provided in the Get Transaction Contacts Import Status API, which is likely already being called.

Sample Definitions

Instead of using a sampleDefinitionId in the Create Sample API call, the sampleCriteria from the sample definition will be used directly in the Create Sample call. For example, the payload to create a sample definition might look like this:

{  
   "sampleCriteria": {  
     "simpleFilter": {  
       "comparison": "notEmpty",  
       "field": "email",  
       "filterType": "infoFieldState"  
     }  
   },  
   "maxSampleSize": 100000  
 }

You will simply take the object set to sampleCriteria and set it to the sampleCriteria key in the Create Sample call.