List Distributions Public API Changes

What are the changes?

Change 1: As part of our commitment to improving the performance and reliability of our APIs, we have identified two APIs (List Distributions and List SMS Distributions) that require pagination scheme updates to fully support large data sets.

When listing distributions or SMS distributions requires multiple pages, the second page of the call is requested by providing the nextPage value returned by the first call. The format of the url returned by this call will replace the offset value with skipToken.

Old Response

"result": {
   "elements": [
     {
       "id": "SMSD_GXMCgpmBVJsvM3g",
       "ownerId": "UR_eDPqMQLv8yQZnIF",
          .
          .
          .
     }
   ],
 
   "nextPage": https://yourdatacenter.qualtrics.com/API/v3/distributions/sms?offset=5
}

New Response

"result": {
   "elements": [
     {
       "id": "SMSD_GXMCgpmBVJsvM3g",
       "ownerId": "UR_eDPqMQLv8yQZnIF",
          .
          .
          .
     }
   ],
 
   "nextPage": "https://yourdatacenter.qualtrics.com/API/v3/distributions/sms?skipToken=K2JRQb7bUY371DhOMYtrwA%3D%3D"
}

Change 2: List Distributions will no longer return the embeddedData field or the message.messageText field and will now include the message.messageType field as enum (Inline or Library) to distinguish the type of message.

{
 "result": {
   "elements": [
     {
       "id": "EMD_1234567890abcde",
          .
          .
          .
       "message": {
         "libraryId": "UR_1M4aHozEkSxUfCl",
         "messageId": "MS_0Vdgn7nLGSQBlYN",
         "messageType": "Library",
         "messageText": "Example Message Text"
       },
       "embeddedData": {}
     }
   ]

What action do I need to take?

Both of these changes will take effect for all customers on June 01, 2022

Change 1: If your calls to this API manually construct the call for the next page, please update it to make the call provided in the nextPage of the previous call. You should update your API call if you are planning to continue to use these APIs.

If you want to opt into the new pagination scheme for testing, you can set a query parameter useNewPaginationScheme=true to force the API to use the new behavior; that is to return the skipToken instead of offset.

If your code already uses the value from nextPage to request the following page, there is no action required on your side.

Change 2: If your calls to List Distributions do not rely on messageText or embeddedData, there is no action required.

If your calls to List Distributions relies on embeddedData, you will need to call Get Distribution for the specific DistributionId to retrieve this data.

If your calls to List Distributions relies on messageText and this text is now an inline message message, you will need to call Get Distribution or [Get SMS Distribution] for the specific DistributionId as the message text is now part of the Get Distribution response.

If your calls to List Distributions relies on messageText and this text is now a library message message, the message text can be found using the Get Library Message endpoint

What if I have questions?

If you have a question about these List Distributions Public 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.