{"_id":"5982240e1ac132001edf17be","project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":61,"createdAt":"2015-06-19T16:35:26.435Z","releaseDate":"2015-06-19T16:35:26.435Z","categories":["558444cfafccfd0d00fcb2bc","558444cfafccfd0d00fcb2bd","55ad4ce733616a0d00599d2e","55ad4cef6aadf20d0015b764","55ad4cf36aadf20d0015b765","55ad4cfb24cf160d0013584f","55ad4d0024cf160d00135850","55ad4d0a24cf160d00135851","55ad4d0d24cf160d00135852","55ad4d126aadf20d0015b766","55ad4d1624cf160d00135853","55ad4d1933616a0d00599d2f","55ad4d2233616a0d00599d30","55ad4d2e24cf160d00135854","55d35b6bf77e6d0d00b1b092","55d3649a0168850d0073f14a","55d366d40168850d0073f15a","55d37fcff77e6d0d00b1b13f","55d383e50168850d0073f1e1","55d3ac26c336ec0d007c2251","55d3c51cb2330119009c31db","55d3c59bfe37111900e536f3","55d3c5a7fe37111900e536f4","55d3c5b4fe37111900e536f5","55d3c5d4fe37111900e536f6","55d3c5d6b2330119009c31df","55d3c5d71f478b170077c164","55d3c687b2330119009c31e4","55d3c6a4fe37111900e536f9","55d3c6befe37111900e536fa","55d3c6e8d2c66f0d00497f93","55d49dcfd7c16b2d007de905","55d4ca8f5082980d0009c79b","55d4cab9c95a3d2f0069ad3d","55d4d279c95a3d2f0069ad60","55d4d9355082980d0009c7e1","55d4f6b5988e130d000b3eb1","55d64dc8e60a2f0d00b88ecb","5627ca43fcbbc621004ec07d","56c64a0d8f98b50d0012c37c","56f1b8b13eb62a34003ea041","56f1b9df4476fb2200795e8c","57f6907dca5e5d1700039ae9","591dd06ca266c423002ec4ca","59234825e465c11900922518","5936f82eaa591e0027638d57","59972f54fd7078001992c136","599c6da8f180820025f14909","59b054613c3e1b0019cf27d9","59b1ceca2d6231003ad73e5f","59b1cf1857911600382e0dc4","59b1cf2730f3d60010c30ef7","59b1cf385d4b89003035441a","59b1cf5857911600382e0dc6","59bc2c4e26ac9b0010a8b753","59bc2ce20b3eb30010657b70","59f0c793ba3bc90030f413ab","59f0cd62f5ecda00325294b9","59fb55a8e8d0f600101aedc3","59fcb05c067f8d0028613f86","5a2af4a1bc5fba00283909c1","5a83673b0e56010012138c12"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"category":{"_id":"59234825e465c11900922518","__v":0,"version":"558444ceafccfd0d00fcb2bb","project":"55843604fd8d910d007b9502","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-22T20:20:53.281Z","from_sync":false,"order":1,"slug":"using-the-qualtrics-api","title":"Using the Qualtrics APIs"},"user":"5919f13aff66b00f00f1948c","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-02T19:12:14.272Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"This guide describes APIs for obtaining information about a survey's distributions. Distributions allow you to manage a survey's requests for responses. There are three types of distributions you can make to email recipients:\n\n- Invites (invitations to take a survey)\n- Reminders (reminders to take a survey sent to those who have not taken it yet) \n- Thank yous (thanking users who took the survey)\n\nFor more information about the Distributions, see [Distributions Overview](https://www.qualtrics.com/support/survey-platform/distributions-module/distributions-overview/).\n\nThis guide contains information about these APIs:\n\n- [Get Distribution](#get-distribution)\n- [List Distributions](#list-distributions)\n[block:api-header]\n{\n  \"title\": \"Get Distribution\"\n}\n[/block]\nThe Get Distribution API allows you to obtain information about a survey's distribution. The information returned consists of the following:\n\n- The distribution's creation, modification, and send dates\n- Details about the distribution email's headers (subject, from address, reply to address, and from name)\n- The organization's ID\n- Information about the distribution's recipients (including the contact ID for distributions to a single recipient,  the mailing list ID for the recipient mailing list, the library ID that identifies the library containing the mailing list, and the sample ID that identifies the sample if the distribution is sent to a subset of the mailing list recipients)\n- Counts of surveys started and finished\n- Counts of emails sent, bounced, blocked, failed, opened by the user, and skipped\n- Status of the distribution\n- Type of distribution\n- Information about the survey including the survey link's expiration date, type of link, and survey ID\n\nThe following sample shows how to use the Get Distribution API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Distribution\\n\\nimport os\\nimport requests\\n\\n#Setting user Parameters\\napiToken = os.environ[\\\"Q_API_TOKEN\\\"]\\ndataCenter = os.environ[\\\"Q_DATA_CENTER\\\"]\\n\\ndistributionId = \\\"EMD_123456\\\"\\nsurveyId = \\\"SV_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/distributions/{1}?surveyId={2}\\\".format(dataCenter, distributionId, surveyId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following shows an example response object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"8417d844-0e60-4ec7-9a17-574a896669dc\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"createdDate\\\": \\\"2017-05-16T17:59:31Z\\\",\\n        \\\"headers\\\": {\\n            \\\"fromEmail\\\": \\\"noreply:::at:::example.com\\\",\\n            \\\"fromName\\\": \\\"John Smith\\\",\\n            \\\"replyToEmail\\\": \\\"jsmith@example.com\\\",\\n            \\\"subject\\\": \\\"Survey Request\\\"\\n        },\\n        \\\"id\\\": \\\"EMD_12345678\\\",\\n        \\\"message\\\": {\\n            \\\"libraryId\\\": null,\\n            \\\"messageId\\\": null,\\n            \\\"messageText\\\": null\\n        },\\n        \\\"modifiedDate\\\": \\\"2017-05-16T17:59:55Z\\\",\\n        \\\"organizationId\\\": \\\"testorg\\\",\\n        \\\"ownerId\\\": \\\"UR_12345678\\\",\\n        \\\"parentDistributionId\\\": null,\\n        \\\"recipients\\\": {\\n            \\\"contactId\\\": null,\\n            \\\"libraryId\\\": \\\"UR_1234567\\\",\\n            \\\"mailingListId\\\": \\\"ML_12378\\\",\\n            \\\"sampleId\\\": null\\n        },\\n        \\\"requestStatus\\\": \\\"Done\\\",\\n        \\\"requestType\\\": \\\"Invite\\\",\\n        \\\"sendDate\\\": \\\"2017-05-16T17:59:00Z\\\",\\n        \\\"stats\\\": {\\n            \\\"blocked\\\": 0,\\n            \\\"bounced\\\": 0,\\n            \\\"complaints\\\": 0,\\n            \\\"failed\\\": 0,\\n            \\\"finished\\\": 1,\\n            \\\"opened\\\": 1,\\n            \\\"sent\\\": 1,\\n            \\\"skipped\\\": 0,\\n            \\\"started\\\": 1\\n        },\\n        \\\"surveyLink\\\": {\\n            \\\"expirationDate\\\": \\\"2017-07-15T17:59:00Z\\\",\\n            \\\"linkType\\\": \\\"Individual\\\",\\n            \\\"surveyId\\\": \\\"SV_123456\\\"\\n        }\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response object\"\n    }\n  ]\n}\n[/block]\nThe following describes the response object:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**createdDate**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**headers**\",\n    \"1-1\": \"Object\",\n    \"2-0\": \"**id**\",\n    \"2-1\": \"String\",\n    \"3-0\": \"**message**\",\n    \"3-1\": \"Object\",\n    \"4-0\": \"**modifiedDate**\",\n    \"4-1\": \"String\",\n    \"5-0\": \"**organizationId**\",\n    \"5-1\": \"String\",\n    \"6-0\": \"**ownerId**\",\n    \"6-1\": \"String\",\n    \"7-0\": \"**parentDistributionId**\",\n    \"7-1\": \"String\",\n    \"8-0\": \"**recipients**\",\n    \"8-1\": \"Object\",\n    \"9-0\": \"**requestStatus**\",\n    \"9-1\": \"String\",\n    \"10-0\": \"**requestType**\",\n    \"10-1\": \"String\",\n    \"11-0\": \"**sendDate**\",\n    \"11-1\": \"String\",\n    \"12-0\": \"**stats**\",\n    \"12-1\": \"Object\",\n    \"13-0\": \"**surveyLink**\",\n    \"13-1\": \"Object\",\n    \"0-2\": \"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](doc:dates-and-times) for more information.\",\n    \"1-2\": \"An object that describes the email distribution's headers. See [The headers Object](#section-the-headers-object) below for more information.\",\n    \"2-2\": \"This distributions identifier. Starts with **EMD_**.\",\n    \"3-2\": \"An object that represents the message sent to email recipients. See [The message Object](#section-the-message-object) below for more information\",\n    \"4-2\": \"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](doc:dates-and-times) for more information.\",\n    \"5-2\": \"The organization ID your account is associated with. Also referred in the example code as the data center ID.\",\n    \"6-2\": \"The user ID of the owner of this distribution.\",\n    \"7-2\": \"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**.\",\n    \"8-2\": \"The email recipients of this distribution. For more information see [The recipients Object](#section-the-recipients-object) below.\",\n    \"9-2\": \"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.\",\n    \"10-2\": \"The distribution's type. Types include **Invite**, **Reminder**, and **ThankYou**.\",\n    \"11-2\": \"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](doc: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.\",\n    \"12-2\": \"Information about the number of emails sent and how many surveys have been started and finished. For more information, see [The stats Object](#section-the-stats-object) below.\",\n    \"13-2\": \"Information about the survey link associated with this distribution. For more information about this object, see [The surveyLink Object](#section-the-surveylink-object) below.\"\n  },\n  \"cols\": 3,\n  \"rows\": 14\n}\n[/block]\n### The headers Object\n\nThe **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:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**fromEmail**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**fromName**\",\n    \"1-1\": \"String\",\n    \"2-0\": \"**replyToEmail**\",\n    \"2-1\": \"String\",\n    \"3-0\": \"**subject**\",\n    \"3-1\": \"String\",\n    \"0-2\": \"The email address of the sender. The default is **noreply@qemailserver.com**.\",\n    \"1-2\": \"The name of the sender. Typically the account owner's name, for instance, **John Doe**.\",\n    \"2-2\": \"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).\",\n    \"3-2\": \"The email's subject line.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n### The message Object\n\nThe **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.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**libraryId**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**messageId**\",\n    \"1-1\": \"String\",\n    \"2-0\": \"**messageText**\",\n    \"2-1\": \"String\",\n    \"0-2\": \"Indicates the ID of the library where the message body text is saved (in the messages library).\",\n    \"1-2\": \"The ID of the saved message in the message library.\",\n    \"2-2\": \"If fixed text was used to create the message, the message text is here, otherwise **null**.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n### The recipients Object\n\nThe **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**. \n\nThere are three possibilities for the **recipients** object:\n\n1. A single recipient. In this case, **contactId** is not **null** and indicates the contact's ID. All other values are **null**.\n2. 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.\n3. A sample. A sample is a subset of contacts and this value refers to the sample's ID.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**contactId**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**libraryId**\",\n    \"1-1\": \"String\",\n    \"2-0\": \"**mailingListId**\",\n    \"2-1\": \"String\",\n    \"3-0\": \"**sampleId**\",\n    \"3-1\": \"String\",\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"If the email distribution is sent to a single recipient, this value is that contact's user ID. Otherwise, it is **null**.\",\n    \"1-2\": \"The library ID of the library that contains the mailing list identified by **mailingListId**.\",\n    \"2-2\": \"The mailing list ID that contains the contacts for this distribution.\",\n    \"3-2\": \"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](https://www.qualtrics.com/support/survey-platform/contacts/contacts-sample/) for more information.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n### The stats Object\n\nThe **stats** object contains information about the following:\n\n- Counts of survey events (**started** and **finished**)\n- Counts of email distribution events (all remaining members)\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**blocked**\",\n    \"0-1\": \"Number\",\n    \"1-0\": \"**bounced**\",\n    \"1-1\": \"Number\",\n    \"2-0\": \"**complaints**\",\n    \"2-1\": \"Number\",\n    \"3-0\": \"**failed**\",\n    \"3-1\": \"Number\",\n    \"4-0\": \"**finished**\",\n    \"4-1\": \"Number\",\n    \"5-0\": \"**opened**\",\n    \"5-1\": \"Number\",\n    \"6-0\": \"**sent**\",\n    \"6-1\": \"Number\",\n    \"7-0\": \"**skipped**\",\n    \"7-1\": \"Number\",\n    \"8-0\": \"**started**\",\n    \"8-1\": \"Number\",\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"5-2\": \"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.\",\n    \"1-2\": \"The number of emails that were rejected by the destination mail server.\",\n    \"3-2\": \"The number of failed emails. Emails fail if the recipient's address was not properly formatted.\",\n    \"7-2\": \"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.\",\n    \"8-2\": \"The number of surveys that recipients have started.\",\n    \"4-2\": \"The number of contacts that have reached the end of the survey and submitted their answers.\",\n    \"6-2\": \"The total number of emails sent.\",\n    \"0-2\": \"The number of emails that were blocked.\",\n    \"2-2\": \"The number of emails rejected because they appeared to be spam or because the IP address was blacklisted.\"\n  },\n  \"cols\": 3,\n  \"rows\": 9\n}\n[/block]\n### The surveyLink Object\n\nThe **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**.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**expirationDate**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**linkType**\",\n    \"1-1\": \"String\",\n    \"2-0\": \"**surveyId**\",\n    \"2-1\": \"String\",\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"2-2\": \"Identifies the survey ID\",\n    \"0-2\": \"The survey link's expiration date (as an ISO 8601 date). See [Dates and Times](doc:dates-and-times) for more information.\",\n    \"1-2\": \"The link type is **Individual**, **Anonymous**, or **Multiple**. See [Understanding the Individual Link](https://www.qualtrics.com/support/survey-platform/distributions-module/email-distribution/emails/emails-overview#UnderstandingTheIndividualLink) for more information about the various link types.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"List Distributions\"\n}\n[/block]\nThe List Distributions API provides information about all distributions associated with a specified survey Id. The information includes all of the information that is returned with Get Distribution for each distribution.\n\nThe following example shows how to retrieve information about the distributions: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# List Distributions\\n\\nimport os\\nimport requests\\n\\n#Setting user Parameters\\napiToken = os.environ[\\\"Q_API_TOKEN\\\"]\\ndataCenter = os.environ[\\\"Q_DATA_CENTER\\\"]\\n\\nsurveyId = \\\"SV_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/distributions?surveyId={1}\\\".format(dataCenter, surveyId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe example below shows the response object:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"8808290c-d391-4991-8382-35583f025a37\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"createdDate\\\": \\\"2017-08-08T15:10:48Z\\\",\\n                \\\"headers\\\": {\\n                    \\\"fromEmail\\\": \\\"noreply@qemailserver.com\\\",\\n                    \\\"fromName\\\": \\\"John Doe\\\",\\n                    \\\"replyToEmail\\\": \\\"jd@example.com,\\n                    \\\"subject\\\": \\\"Thanks\\\"\\n                },\\n                \\\"id\\\": \\\"EMD_784635\\\",\\n                \\\"message\\\": {\\n                    \\\"libraryId\\\": null,\\n                    \\\"messageId\\\": null,\\n                    \\\"messageText\\\": null\\n                },\\n                \\\"modifiedDate\\\": \\\"2017-08-08T15:10:48Z\\\",\\n                \\\"organizationId\\\": \\\"testorg\\\",\\n                \\\"ownerId\\\": \\\"UR_123456\\\",\\n                \\\"parentDistributionId\\\": \\\"EMD_123456\\\",\\n                \\\"recipients\\\": {\\n                    \\\"contactId\\\": null,\\n                    \\\"libraryId\\\": null,\\n                    \\\"mailingListId\\\": null,\\n                    \\\"sampleId\\\": null\\n                },\\n                \\\"requestStatus\\\": \\\"Pending\\\",\\n                \\\"requestType\\\": \\\"ThankYou\\\",\\n                \\\"sendDate\\\": \\\"2017-08-08T16:10:00Z\\\",\\n                \\\"stats\\\": {\\n                    \\\"blocked\\\": 0,\\n                    \\\"bounced\\\": 0,\\n                    \\\"complaints\\\": 0,\\n                    \\\"failed\\\": 0,\\n                    \\\"finished\\\": 0,\\n                    \\\"opened\\\": 0,\\n                    \\\"sent\\\": 0,\\n                    \\\"skipped\\\": 0,\\n                    \\\"started\\\": 0\\n                },\\n                \\\"surveyLink\\\": {\\n                    \\\"expirationDate\\\": null,\\n                    \\\"linkType\\\": null,\\n                    \\\"surveyId\\\": \\\"SV_123456\\\"\\n                }\\n            },\\n            {\\n                \\\"createdDate\\\": \\\"2017-08-08T14:48:28Z\\\",\\n                \\\"headers\\\": {\\n                    \\\"fromEmail\\\": \\\"noreply@qemailserver.com\\\",\\n                    \\\"fromName\\\": \\\"John Doe\\\",\\n                    \\\"replyToEmail\\\": \\\"jd@example.com\\\",\\n                    \\\"subject\\\": \\\"Reminder message\\\"\\n                },\\n                \\\"id\\\": \\\"EMD_6543\\\",\\n                \\\"message\\\": {\\n                    \\\"libraryId\\\": \\\"UR_123456\\\",\\n                    \\\"messageId\\\": \\\"MS_123456\\\",\\n                    \\\"messageText\\\": null\\n                },\\n                \\\"modifiedDate\\\": \\\"2017-08-08T15:26:15Z\\\",\\n                \\\"organizationId\\\": \\\"testorg\\\",\\n                \\\"ownerId\\\": \\\"UR_123456\\\",\\n                \\\"parentDistributionId\\\": \\\"EMD_123456\\\",\\n                \\\"recipients\\\": {\\n                    \\\"contactId\\\": null,\\n                    \\\"libraryId\\\": null,\\n                    \\\"mailingListId\\\": null,\\n                    \\\"sampleId\\\": null\\n                },\\n                \\\"requestStatus\\\": \\\"Done\\\",\\n                \\\"requestType\\\": \\\"Reminder\\\",\\n                \\\"sendDate\\\": \\\"2017-08-08T14:48:00Z\\\",\\n                \\\"stats\\\": {\\n                    \\\"blocked\\\": 0,\\n                    \\\"bounced\\\": 0,\\n                    \\\"complaints\\\": 0,\\n                    \\\"failed\\\": 0,\\n                    \\\"finished\\\": 0,\\n                    \\\"opened\\\": 3,\\n                    \\\"sent\\\": 3,\\n                    \\\"skipped\\\": 0,\\n                    \\\"started\\\": 0\\n                },\\n                \\\"surveyLink\\\": {\\n                    \\\"expirationDate\\\": null,\\n                    \\\"linkType\\\": null,\\n                    \\\"surveyId\\\": \\\"SV_123456\\\"\\n                }\\n            },\\n            {\\n                \\\"createdDate\\\": \\\"2017-05-16T17:59:31Z\\\",\\n                \\\"headers\\\": {\\n                    \\\"fromEmail\\\": \\\"noreply@qemailserver.com\\\",\\n                    \\\"fromName\\\": \\\"John Doe\\\",\\n                    \\\"replyToEmail\\\": \\\"jd@example.com\\\",\\n                    \\\"subject\\\": \\\"Invitation to take a survey\\\"\\n                },\\n                \\\"id\\\": \\\"EMD_123456\\\",\\n                \\\"message\\\": {\\n                    \\\"libraryId\\\": null,\\n                    \\\"messageId\\\": null,\\n                    \\\"messageText\\\": null\\n                },\\n                \\\"modifiedDate\\\": \\\"2017-05-16T17:59:55Z\\\",\\n                \\\"organizationId\\\": \\\"testorg\\\",\\n                \\\"ownerId\\\": \\\"UR_123456\\\",\\n                \\\"parentDistributionId\\\": null,\\n                \\\"recipients\\\": {\\n                    \\\"contactId\\\": null,\\n                    \\\"libraryId\\\": \\\"UR_123456\\\",\\n                    \\\"mailingListId\\\": \\\"ML_23456\\\",\\n                    \\\"sampleId\\\": null\\n                },\\n                \\\"requestStatus\\\": \\\"Done\\\",\\n                \\\"requestType\\\": \\\"Invite\\\",\\n                \\\"sendDate\\\": \\\"2017-05-16T17:59:00Z\\\",\\n                \\\"stats\\\": {\\n                    \\\"blocked\\\": 0,\\n                    \\\"bounced\\\": 0,\\n                    \\\"complaints\\\": 0,\\n                    \\\"failed\\\": 0,\\n                    \\\"finished\\\": 1,\\n                    \\\"opened\\\": 1,\\n                    \\\"sent\\\": 1,\\n                    \\\"skipped\\\": 0,\\n                    \\\"started\\\": 1\\n                },\\n                \\\"surveyLink\\\": {\\n                    \\\"expirationDate\\\": \\\"2017-07-15T17:59:00Z\\\",\\n                    \\\"linkType\\\": \\\"Individual\\\",\\n                    \\\"surveyId\\\": \\\"SV_123456\\\"\\n                }\\n            }\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe response object is a collection of all the survey's distribution objects. The objects are described earlier in the [Get Distribution section](#get-distribution).","excerpt":"APIs for querying distributions","slug":"getting-information-about-distributions","type":"basic","title":"Getting Information about Distributions"}

Getting Information about Distributions

APIs for querying distributions

This guide describes APIs for obtaining information about a survey's distributions. Distributions allow you to manage a survey's requests for responses. There are three types of distributions you can make to email recipients: - Invites (invitations to take a survey) - Reminders (reminders to take a survey sent to those who have not taken it yet) - Thank yous (thanking users who took the survey) For more information about the Distributions, see [Distributions Overview](https://www.qualtrics.com/support/survey-platform/distributions-module/distributions-overview/). This guide contains information about these APIs: - [Get Distribution](#get-distribution) - [List Distributions](#list-distributions) [block:api-header] { "title": "Get Distribution" } [/block] The Get Distribution API allows you to obtain information about a survey's distribution. The information returned consists of the following: - The distribution's creation, modification, and send dates - Details about the distribution email's headers (subject, from address, reply to address, and from name) - The organization's ID - Information about the distribution's recipients (including the contact ID for distributions to a single recipient, the mailing list ID for the recipient mailing list, the library ID that identifies the library containing the mailing list, and the sample ID that identifies the sample if the distribution is sent to a subset of the mailing list recipients) - Counts of surveys started and finished - Counts of emails sent, bounced, blocked, failed, opened by the user, and skipped - Status of the distribution - Type of distribution - Information about the survey including the survey link's expiration date, type of link, and survey ID The following sample shows how to use the Get Distribution API: [block:code] { "codes": [ { "code": "# Get Distribution\n\nimport os\nimport requests\n\n#Setting user Parameters\napiToken = os.environ[\"Q_API_TOKEN\"]\ndataCenter = os.environ[\"Q_DATA_CENTER\"]\n\ndistributionId = \"EMD_123456\"\nsurveyId = \"SV_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/distributions/{1}?surveyId={2}\".format(dataCenter, distributionId, surveyId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following shows an example response object: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"8417d844-0e60-4ec7-9a17-574a896669dc\"\n },\n \"result\": {\n \"createdDate\": \"2017-05-16T17:59:31Z\",\n \"headers\": {\n \"fromEmail\": \"noreply@example.com\",\n \"fromName\": \"John Smith\",\n \"replyToEmail\": \"jsmith@example.com\",\n \"subject\": \"Survey Request\"\n },\n \"id\": \"EMD_12345678\",\n \"message\": {\n \"libraryId\": null,\n \"messageId\": null,\n \"messageText\": null\n },\n \"modifiedDate\": \"2017-05-16T17:59:55Z\",\n \"organizationId\": \"testorg\",\n \"ownerId\": \"UR_12345678\",\n \"parentDistributionId\": null,\n \"recipients\": {\n \"contactId\": null,\n \"libraryId\": \"UR_1234567\",\n \"mailingListId\": \"ML_12378\",\n \"sampleId\": null\n },\n \"requestStatus\": \"Done\",\n \"requestType\": \"Invite\",\n \"sendDate\": \"2017-05-16T17:59:00Z\",\n \"stats\": {\n \"blocked\": 0,\n \"bounced\": 0,\n \"complaints\": 0,\n \"failed\": 0,\n \"finished\": 1,\n \"opened\": 1,\n \"sent\": 1,\n \"skipped\": 0,\n \"started\": 1\n },\n \"surveyLink\": {\n \"expirationDate\": \"2017-07-15T17:59:00Z\",\n \"linkType\": \"Individual\",\n \"surveyId\": \"SV_123456\"\n }\n }\n}", "language": "json", "name": "Response object" } ] } [/block] The following describes the response object: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**createdDate**", "0-1": "String", "1-0": "**headers**", "1-1": "Object", "2-0": "**id**", "2-1": "String", "3-0": "**message**", "3-1": "Object", "4-0": "**modifiedDate**", "4-1": "String", "5-0": "**organizationId**", "5-1": "String", "6-0": "**ownerId**", "6-1": "String", "7-0": "**parentDistributionId**", "7-1": "String", "8-0": "**recipients**", "8-1": "Object", "9-0": "**requestStatus**", "9-1": "String", "10-0": "**requestType**", "10-1": "String", "11-0": "**sendDate**", "11-1": "String", "12-0": "**stats**", "12-1": "Object", "13-0": "**surveyLink**", "13-1": "Object", "0-2": "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](doc:dates-and-times) for more information.", "1-2": "An object that describes the email distribution's headers. See [The headers Object](#section-the-headers-object) below for more information.", "2-2": "This distributions identifier. Starts with **EMD_**.", "3-2": "An object that represents the message sent to email recipients. See [The message Object](#section-the-message-object) below for more information", "4-2": "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](doc:dates-and-times) for more information.", "5-2": "The organization ID your account is associated with. Also referred in the example code as the data center ID.", "6-2": "The user ID of the owner of this distribution.", "7-2": "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**.", "8-2": "The email recipients of this distribution. For more information see [The recipients Object](#section-the-recipients-object) below.", "9-2": "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.", "10-2": "The distribution's type. Types include **Invite**, **Reminder**, and **ThankYou**.", "11-2": "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](doc: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.", "12-2": "Information about the number of emails sent and how many surveys have been started and finished. For more information, see [The stats Object](#section-the-stats-object) below.", "13-2": "Information about the survey link associated with this distribution. For more information about this object, see [The surveyLink Object](#section-the-surveylink-object) below." }, "cols": 3, "rows": 14 } [/block] ### 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: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**fromEmail**", "0-1": "String", "1-0": "**fromName**", "1-1": "String", "2-0": "**replyToEmail**", "2-1": "String", "3-0": "**subject**", "3-1": "String", "0-2": "The email address of the sender. The default is **noreply@qemailserver.com**.", "1-2": "The name of the sender. Typically the account owner's name, for instance, **John Doe**.", "2-2": "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).", "3-2": "The email's subject line." }, "cols": 3, "rows": 4 } [/block] ### 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. [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**libraryId**", "0-1": "String", "1-0": "**messageId**", "1-1": "String", "2-0": "**messageText**", "2-1": "String", "0-2": "Indicates the ID of the library where the message body text is saved (in the messages library).", "1-2": "The ID of the saved message in the message library.", "2-2": "If fixed text was used to create the message, the message text is here, otherwise **null**." }, "cols": 3, "rows": 3 } [/block] ### 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: 1. A single recipient. In this case, **contactId** is not **null** and indicates the contact's ID. All other values are **null**. 2. 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. 3. A sample. A sample is a subset of contacts and this value refers to the sample's ID. [block:parameters] { "data": { "0-0": "**contactId**", "0-1": "String", "1-0": "**libraryId**", "1-1": "String", "2-0": "**mailingListId**", "2-1": "String", "3-0": "**sampleId**", "3-1": "String", "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-2": "If the email distribution is sent to a single recipient, this value is that contact's user ID. Otherwise, it is **null**.", "1-2": "The library ID of the library that contains the mailing list identified by **mailingListId**.", "2-2": "The mailing list ID that contains the contacts for this distribution.", "3-2": "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](https://www.qualtrics.com/support/survey-platform/contacts/contacts-sample/) for more information." }, "cols": 3, "rows": 4 } [/block] ### 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) [block:parameters] { "data": { "0-0": "**blocked**", "0-1": "Number", "1-0": "**bounced**", "1-1": "Number", "2-0": "**complaints**", "2-1": "Number", "3-0": "**failed**", "3-1": "Number", "4-0": "**finished**", "4-1": "Number", "5-0": "**opened**", "5-1": "Number", "6-0": "**sent**", "6-1": "Number", "7-0": "**skipped**", "7-1": "Number", "8-0": "**started**", "8-1": "Number", "h-0": "Member", "h-1": "Type", "h-2": "Description", "5-2": "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.", "1-2": "The number of emails that were rejected by the destination mail server.", "3-2": "The number of failed emails. Emails fail if the recipient's address was not properly formatted.", "7-2": "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.", "8-2": "The number of surveys that recipients have started.", "4-2": "The number of contacts that have reached the end of the survey and submitted their answers.", "6-2": "The total number of emails sent.", "0-2": "The number of emails that were blocked.", "2-2": "The number of emails rejected because they appeared to be spam or because the IP address was blacklisted." }, "cols": 3, "rows": 9 } [/block] ### 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**. [block:parameters] { "data": { "0-0": "**expirationDate**", "0-1": "String", "1-0": "**linkType**", "1-1": "String", "2-0": "**surveyId**", "2-1": "String", "h-0": "Member", "h-1": "Type", "h-2": "Description", "2-2": "Identifies the survey ID", "0-2": "The survey link's expiration date (as an ISO 8601 date). See [Dates and Times](doc:dates-and-times) for more information.", "1-2": "The link type is **Individual**, **Anonymous**, or **Multiple**. See [Understanding the Individual Link](https://www.qualtrics.com/support/survey-platform/distributions-module/email-distribution/emails/emails-overview#UnderstandingTheIndividualLink) for more information about the various link types." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "title": "List Distributions" } [/block] The List Distributions API provides information about all distributions associated with a specified survey Id. The information includes all of the information that is returned with Get Distribution for each distribution. The following example shows how to retrieve information about the distributions: [block:code] { "codes": [ { "code": "# List Distributions\n\nimport os\nimport requests\n\n#Setting user Parameters\napiToken = os.environ[\"Q_API_TOKEN\"]\ndataCenter = os.environ[\"Q_DATA_CENTER\"]\n\nsurveyId = \"SV_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/distributions?surveyId={1}\".format(dataCenter, surveyId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The example below shows the response object: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"8808290c-d391-4991-8382-35583f025a37\"\n },\n \"result\": {\n \"elements\": [\n {\n \"createdDate\": \"2017-08-08T15:10:48Z\",\n \"headers\": {\n \"fromEmail\": \"noreply@qemailserver.com\",\n \"fromName\": \"John Doe\",\n \"replyToEmail\": \"jd@example.com,\n \"subject\": \"Thanks\"\n },\n \"id\": \"EMD_784635\",\n \"message\": {\n \"libraryId\": null,\n \"messageId\": null,\n \"messageText\": null\n },\n \"modifiedDate\": \"2017-08-08T15:10:48Z\",\n \"organizationId\": \"testorg\",\n \"ownerId\": \"UR_123456\",\n \"parentDistributionId\": \"EMD_123456\",\n \"recipients\": {\n \"contactId\": null,\n \"libraryId\": null,\n \"mailingListId\": null,\n \"sampleId\": null\n },\n \"requestStatus\": \"Pending\",\n \"requestType\": \"ThankYou\",\n \"sendDate\": \"2017-08-08T16:10:00Z\",\n \"stats\": {\n \"blocked\": 0,\n \"bounced\": 0,\n \"complaints\": 0,\n \"failed\": 0,\n \"finished\": 0,\n \"opened\": 0,\n \"sent\": 0,\n \"skipped\": 0,\n \"started\": 0\n },\n \"surveyLink\": {\n \"expirationDate\": null,\n \"linkType\": null,\n \"surveyId\": \"SV_123456\"\n }\n },\n {\n \"createdDate\": \"2017-08-08T14:48:28Z\",\n \"headers\": {\n \"fromEmail\": \"noreply@qemailserver.com\",\n \"fromName\": \"John Doe\",\n \"replyToEmail\": \"jd@example.com\",\n \"subject\": \"Reminder message\"\n },\n \"id\": \"EMD_6543\",\n \"message\": {\n \"libraryId\": \"UR_123456\",\n \"messageId\": \"MS_123456\",\n \"messageText\": null\n },\n \"modifiedDate\": \"2017-08-08T15:26:15Z\",\n \"organizationId\": \"testorg\",\n \"ownerId\": \"UR_123456\",\n \"parentDistributionId\": \"EMD_123456\",\n \"recipients\": {\n \"contactId\": null,\n \"libraryId\": null,\n \"mailingListId\": null,\n \"sampleId\": null\n },\n \"requestStatus\": \"Done\",\n \"requestType\": \"Reminder\",\n \"sendDate\": \"2017-08-08T14:48:00Z\",\n \"stats\": {\n \"blocked\": 0,\n \"bounced\": 0,\n \"complaints\": 0,\n \"failed\": 0,\n \"finished\": 0,\n \"opened\": 3,\n \"sent\": 3,\n \"skipped\": 0,\n \"started\": 0\n },\n \"surveyLink\": {\n \"expirationDate\": null,\n \"linkType\": null,\n \"surveyId\": \"SV_123456\"\n }\n },\n {\n \"createdDate\": \"2017-05-16T17:59:31Z\",\n \"headers\": {\n \"fromEmail\": \"noreply@qemailserver.com\",\n \"fromName\": \"John Doe\",\n \"replyToEmail\": \"jd@example.com\",\n \"subject\": \"Invitation to take a survey\"\n },\n \"id\": \"EMD_123456\",\n \"message\": {\n \"libraryId\": null,\n \"messageId\": null,\n \"messageText\": null\n },\n \"modifiedDate\": \"2017-05-16T17:59:55Z\",\n \"organizationId\": \"testorg\",\n \"ownerId\": \"UR_123456\",\n \"parentDistributionId\": null,\n \"recipients\": {\n \"contactId\": null,\n \"libraryId\": \"UR_123456\",\n \"mailingListId\": \"ML_23456\",\n \"sampleId\": null\n },\n \"requestStatus\": \"Done\",\n \"requestType\": \"Invite\",\n \"sendDate\": \"2017-05-16T17:59:00Z\",\n \"stats\": {\n \"blocked\": 0,\n \"bounced\": 0,\n \"complaints\": 0,\n \"failed\": 0,\n \"finished\": 1,\n \"opened\": 1,\n \"sent\": 1,\n \"skipped\": 0,\n \"started\": 1\n },\n \"surveyLink\": {\n \"expirationDate\": \"2017-07-15T17:59:00Z\",\n \"linkType\": \"Individual\",\n \"surveyId\": \"SV_123456\"\n }\n }\n ],\n \"nextPage\": null\n }\n}", "language": "json" } ] } [/block] The response object is a collection of all the survey's distribution objects. The objects are described earlier in the [Get Distribution section](#get-distribution).