Getting Information about Distributions

This guide describes the APIs you will use to get information about a survey's distributions. When a survey gets a distribution, the survey is sent to people on the contact list in the distribution. These APIs allow you to see and manage the survey's contacts with its recipients.

There are three types of distributions you can make to email recipients:

Invites	Invitation to take a survey
Reminders	Reminders to take a survey sent to those who have not yet taken it
Thank Yous	Thanking users who took the survey - last survey contact with recipient.

For more information about the Distributions, see Distributions Overview.

This guide contains information about these two APIs:

Get Distribution
List Distributions

Get Distribution

The Get Distribution API will give you all the information about a single distribution for a survey.

This API give you the information necessary to programmatically create reminders within your chosen rules, and to know when to send a thank you distribution. The stats laid out in below are a powerful way to measure the health of your survey's participation, which you can then use to send additional reminders if necessary.

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.

The following sample shows how to use the Get Distribution API:

# List Distribution Links
import urllib
from urllib import request

# Setting user parameters
apiToken = "26Bb1mJtdQNopKLUg7aSTydpXUwnPRuZnCkBjZ3z" 
dataCenter = "st3"
surveyid = "SV_eajskCRbMSRKkRf"
distributionid = "EMD_Vhid09W3Z5ge89i"

# create the query string
params = urllib.parse.urlencode({'surveyId': surveyid})

# build the url
url = "https://{0}.qualtrics.com/API/v3/distributions/{1}?{2}".format(dataCenter,distributionid,params)

# build the request
headers = { "x-api-token": apiToken }
req = urllib.request.Request(url,None,headers)

# make the request and print the results
with urllib.request.urlopen(req) as handler:
    # print the result 
    print(handler.status)
    print(handler.reason)
    data=handler.read()
    print(data)

The following shows an example response object:

{
  "result": {
    "id": "EMD_Vhid09W3Z5ge89i",
    "parentDistributionId": null,
    "ownerId": "UR_cVcNH0elQesua8J",
    "organizationId": "apidocs",
    "requestStatus": "Pending",
    "requestType": "Invite",
    "sendDate": "2019-11-25T01:18:51Z",
    "createdDate": "2019-11-25T01:18:51Z",
    "modifiedDate": "2019-11-24T18:18:52Z",
    "customHeaders": {},
    "headers": {
      "fromEmail": "noreply@example.com",
      "fromName": "John Smith",
      "replyToEmail": "jsmith@example.com",
      "subject": "Survey Request"
    },
    "recipients": {
      "mailingListId": "BT_01gl1yEFWKZZ8y9",
      "contactId": null,
      "libraryId": "UR_cVcNH0elQesua8J",
      "sampleId": null
    },
    "message": {
      "libraryId": "UR_cVcNH0elQesua8J",
      "messageId": "MS_9KAQTRZOeKY9zp3",
      "messageText": null
    },
    "surveyLink": {
      "surveyId": "SV_eajskCRbMSRKkRf",
      "expirationDate": "2020-01-23T22:52:00Z",
      "linkType": "Individual"
    },
    "embeddedData": null,
    "stats": {
      "sent": 0,
      "failed": 0,
      "started": 0,
      "bounced": 0,
      "opened": 0,
      "skipped": 0,
      "finished": 0,
      "complaints": 0,
      "blocked": 0
    }
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "ab324f2e-0b3e-4366-89d6-0830c6d9040d"
  }
}

The following describes the response object:

Member	Type	Description
createdDate	String	The date and time this distribution was created (formatted as an ISO 8601 date). An example createdDate is 2017-05-16T17:59:31Z. See Dates and Times for more information.
headers	Object	An object that describes the email distribution's headers. See The headers Object below for more information.
id	String	This distributions identifier. Starts with EMD_.
message	Object	An object that represents the message sent to email recipients. See The message Object below for more information
modifiedDate	String	The date and time this distribution was modified (formatted as an ISO 8601 date). An example modifiedDate is 2017-05-16T17:59:55Z. See Dates and Times for more information.
organizationId	String	The organization or brand ID associated with your account.
ownerId	String	The user ID of the owner of this distribution.
parentDistributionId	String	The distribution's parent ID. The parent distribution is typically the initial invite (requestType is Invite). Subsequent distributions (usually those with requestType of Reminder or ThankYou) will have their parentDistributionId set to the id of the initial invite. For the initial invite this value is null.
recipients	Object	The email recipients of this distribution. For more information see The recipients Object below.
requestStatus	String	The distribution's status. States include Pending and Done. The Pending state is for email that is scheduled to be sent at a later time.
requestType	String	The distribution's type. Types include Invite, Reminder, and ThankYou.
sendDate	String	The date and time the request will be or was sent (in ISO 8601 format). An example sendDate is 2017-08-07T21:45:00Z. See Dates and Times for more information. Note that this date and time could be in the future if the email distribution is scheduled to send after a delay.
stats	Object	Information about the number of emails sent and how many surveys have been started and finished. For more information, see The stats Object below.
surveyLink	Object	Information about the survey link associated with this distribution. For more information about this object, see The surveyLink Object below.

The headers Object

The headers object (along with the message object) describes the email message sent to recipients of the distribution. The following table provides details about the members of the object:

Member	Type	Description
fromEmail	String	The email address of the sender. The default is noreply@qemailserver.com.
fromName	String	The name of the sender. Typically the account owner's name, for instance, John Doe.
replyToEmail	String	The email address of the sender of the email, for example, john@example.com. This is the address that will receive a message should the recipient of the email choose reply (in most email applications).
subject	String	The email's subject line.

The message Object

The message object contains information about the body of the email message that is sent to survey recipients. Typically, the message is saved in the user's library.

Member	Type	Description
libraryId	String	Indicates the ID of the library where the message body text is saved (in the messages library).
messageId	String	The ID of the saved message in the message library.
messageText	String	If fixed text was used to create the message, the message text is here, otherwise null.

The recipients Object

The recipients object contains information that describes the contacts or subset of contacts who are targeted by the email distribution. All member values are all null if the requestType is not Invite.

There are three possibilities for the recipients object:

A single recipient. In this case, contactId is not null and indicates the contact's lookup ID. The ** mailingListId** and indicates the mailing list ID that the contact is in. All other values are null.
A mailing list. Here, libraryId is set to the ID of the library that contains the mailing list and mailingListId is set to the mailing list's ID.
A sample. A sample is a subset of contacts and this value refers to the sample's ID.

Member	Type	Description
contactId	String	If the email distribution is sent to a single recipient, this value is that contact's ID. Otherwise, it is null.
libraryId	String	The library ID of the library that contains the mailing list identified by mailingListId.
mailingListId	String	The mailing list ID that contains the contacts for this distribution.
sampleId	String	Samples are subsets of a mailing list's contacts. sampleId identifies whether this email distribution is for a sample identified by its sample ID (otherwise null). See Contacts Samples for more information.

The stats Object

The stats object contains information about the following:

Counts of survey events (started and finished)
Counts of email distribution events (all remaining members)

Member	Type	Description
blocked	Number	The number of emails that were blocked.
bounced	Number	The number of emails that were rejected by the destination mail server. See this Support Page for help with bounced emails.
complaints	Number	The number of emails rejected because they appeared to be spam or because the IP address was blacklisted. See this Support Page for help with complaints.
failed	Number	The number of failed emails. Emails fail if the recipient's address was not properly formatted.
finished	Number	The number of contacts that have responses stored including partial responses.
opened	Number	Indicates whether the email recipient opened the message. Note that messages use a web beacon image, so if the user has disabled loading of external images, this count won't increment although the user has opened the message.
sent	Number	The total number of emails sent.
skipped	Number	The number of respondents that were not delivered because of contacts which have already received the maximum number of emails within the timeframe established by your brand administrator.
started	Number	The number of surveys that recipients have started.

The surveyLink Object

The surveyLink object represents the link associated with the distribution. The link is only set if the distribution's requestType is Invite, but surveyId is always set to the ID of the survey that owns this distribution. Otherwise both expirationDate and linkType are null.

Member	Type	Description
expirationDate	String	The survey link's expiration date (as an ISO 8601 date). See Dates and Times for more information.
linkType	String	The link type is Individual, Anonymous, or Multiple. See Survey Link Types for more information about the various link types.
surveyId	String	Identifies the survey ID

List Distributions

The List Distributions API does the same thing as the Get Distributions API, but lists all the distributions for a particular survey. The entire data object given in the Get Distribution section is returned for each distribution.

With this API, you can get an overview of the distribution history for a survey, so you can get a feel for whether the survey needs attention.

The following example shows how to retrieve information about all distributions for a survey:

# List Distribution Links
import urllib
from urllib import request

# Setting user parameters
apiToken = "26Bb1mJtdQNopKLUg7aSTydpXUwnPRuZnCkBjZ3z" 
dataCenter = "st3"
surveyid = "SV_eajskCRbMSRKkRf"

# create the query string
params = urllib.parse.urlencode({'surveyId': surveyid})

# build the url
url = "https://{0}.qualtrics.com/API/v3/distributions/?{1}".format(dataCenter,params)

# build the request
headers = { "x-api-token": apiToken }
req = urllib.request.Request(url,None,headers)

# make the request and print the results
with urllib.request.urlopen(req) as handler:
    # print the result 
    print(handler.status)
    print(handler.reason)
    data=handler.read()
    print(data)

The example below shows the response object:

{
  "result": {
    "elements": [
      {
        "id": "EMD_vPSNvUyf7cevWSX",
        "parentDistributionId": null,
        "ownerId": "UR_cVcNH0elQesua8J",
        "organizationId": "testorg",
        "requestStatus": "Generated",
        "requestType": "GeneratedInvite",
        "sendDate": "2019-11-25T02:19:47Z",
        "createdDate": "2019-11-25T02:19:47Z",
        "modifiedDate": "2019-11-24T19:19:47Z",
        "customHeaders": {},
        "headers": {
          "fromEmail": null,
          "replyToEmail": null,
          "fromName": null
        },
        "recipients": {
          "mailingListId": "CG_er1pwJbK9BZuxo1",
          "contactId": null,
          "libraryId": "UR_cVcNH0elQesua8J",
          "sampleId": null
        },
        "message": {
          "libraryId": null,
          "messageId": null,
          "messageText": null
        },
        "surveyLink": {
          "surveyId": "SV_eajskCRbMSRKkRf",
          "expirationDate": "2019-12-24T07:00:00Z",
          "linkType": "Individual"
        },
        "embeddedData": null,
        "stats": {
          "sent": 0,
          "failed": 0,
          "started": 0,
          "bounced": 0,
          "opened": 0,
          "skipped": 0,
          "finished": 0,
          "complaints": 0,
          "blocked": 0
        }
      },
      {
        "id": "EMD_Vhid09W3Z5ge89i",
        "parentDistributionId": null,
        "ownerId": "UR_cVcNH0elQesua8J",
        "organizationId": "testorg",
        "requestStatus": "Pending",
        "requestType": "Invite",
        "sendDate": "2019-11-25T01:18:51Z",
        "createdDate": "2019-11-25T01:18:51Z",
        "modifiedDate": "2019-11-24T18:18:52Z",
        "customHeaders": {},
        "headers": {
          "fromEmail": "apitest@qualtrics.com",
          "replyToEmail": "noreply@qualtrics.com",
          "fromName": "Api Tester",
          "subject": "Example Subject"
        },
        "recipients": {
          "mailingListId": "BT_01gl1yEFWKZZ8y9",
          "contactId": null,
          "libraryId": "UR_cVcNH0elQesua8J",
          "sampleId": null
        },
        "message": {
          "libraryId": "UR_cVcNH0elQesua8J",
          "messageId": "MS_9KAQTRZOeKY9zp3",
          "messageText": null
        },
        "surveyLink": {
          "surveyId": "SV_eajskCRbMSRKkRf",
          "expirationDate": "2020-01-23T22:52:00Z",
          "linkType": "Individual"
        },
        "embeddedData": null,
        "stats": {
          "sent": 0,
          "failed": 0,
          "started": 0,
          "bounced": 0,
          "opened": 0,
          "skipped": 0,
          "finished": 0,
          "complaints": 0,
          "blocked": 0
        }
      },
      {
        "id": "EMD_25AwefaLHEoQLVH",
        "parentDistributionId": null,
        "ownerId": "UR_cVcNH0elQesua8J",
        "organizationId": "testorg",
        "requestStatus": "Done",
        "requestType": "Invite",
        "sendDate": "2019-11-24T22:52:00Z",
        "createdDate": "2019-11-24T22:52:24Z",
        "modifiedDate": "2019-11-24T15:54:29Z",
        "customHeaders": {},
        "headers": {
          "fromEmail": "noreply@qemailserver.com",
          "replyToEmail": "testowner@gmail.com",
          "fromName": "Test Owner",
          "subject": "Test Survey Subject"
        },
        "recipients": {
          "mailingListId": "CG_er1pwJbK9BZuxo1",
          "contactId": null,
          "libraryId": "UR_cVcNH0elQesua8J",
          "sampleId": null
        },
        "message": {
          "libraryId": null,
          "messageId": null,
          "messageText": null
        },
        "surveyLink": {
          "surveyId": "SV_eajskCRbMSRKkRf",
          "expirationDate": "2020-01-23T22:52:00Z",
          "linkType": "Individual"
        },
        "embeddedData": null,
        "stats": {
          "sent": 0,
          "failed": 2,
          "started": 0,
          "bounced": 0,
          "opened": 0,
          "skipped": 0,
          "finished": 0,
          "complaints": 0,
          "blocked": 0
        }
      }
    ],
    "nextPage": null
  },
  "meta": {
    "httpStatus": "200 - OK",
    "requestId": "ed6656b0-a924-4a63-9534-dc75edc21ff6"
  }
}

The response object is a collection of all the survey's distribution objects. All the objects are described earlier in the Get Distribution section.

Get Distribution​

Code and Qualtrics Support​

The headers Object​

The message Object​

The recipients Object​

The stats Object​

The surveyLink Object​

List Distributions​