{"_id":"5772e5dfda551f0e00be5c07","__v":17,"editedParams":true,"version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":71,"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","5a972f2e77b85a0070e4ebe2","5aa300224ed4b40012c53e1d","5acd20095efd8d000359bb3c","5ad50889c05179000306021e","5af0927a8779670003daff34","5b55a46b282b25000319669e","5ba4b423a1a8660003a6b4dd","5ba969b5bdd51d0003cf152c","5bb87f6ea7fe7b0003b86e02","5bbf51fee658fb000339f503"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"editedParams2":true,"project":"55843604fd8d910d007b9502","githubsync":"","parentDoc":null,"category":{"_id":"55d3c6befe37111900e536fa","pages":["56c25610c866aa1700109ad7"],"version":"558444ceafccfd0d00fcb2bb","__v":1,"project":"55843604fd8d910d007b9502","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-08-18T23:58:54.366Z","from_sync":false,"order":23,"slug":"distributions","title":"Distributions"},"user":"558435c2fb52ee0d0015d190","updates":["59b17f0c376429003027e031"],"next":{"pages":[],"description":""},"createdAt":"2016-06-28T21:02:23.904Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[{"language":"curl","code":"curl -X POST -H 'X-API-TOKEN: yourapitoken' -H 'Content-Type: application/json' -d '{\n    \"surveyLink\": {\n    \t\"surveyId\":\"SV_0iEUsdE4aB4K0Dj\",\n      \"expirationDate\":\"2016-01-16T00:36:42Z\",\n      \"type\":\"Individual\"\n    },\n    \"header\": {\n    \t\"fromEmail\": \"apitest:::at:::qualtrics.com\",\n      \"fromName\": \"Api Tester\",\n      \"replyToEmail\": \"noreply@qualtrics.com\", \n      \"subject\": \"Example Subject\"\n    },\n    \"message\": {\n    \t\"libraryId\":\"UR_1M4aHozEkSxUfCl\",\n      \"messageId\":\"MS_0Vdgn7nLGSQBlYN\"\n    },\n    \"recipients\": {\n    \t\"mailingListId\":\"ML_01gl1yHFWKSU8y9\"\n    },\n    \"sendDate\": \"2015-11-17T00:36:42Z\"\n}' 'https://yourdatacenterid.qualtrics.com/API/v3/distributions'","name":"cURL (w/ mailingListId)"},{"code":"curl -X POST -H 'X-API-TOKEN: yourapitoken' -H 'Content-Type: application/json' -d '{\n    \"surveyLink\": {\n      \"surveyId\":\"SV_0iEUsdE4aB4K0Dj\",\n      \"expirationDate\":\"2016-01-16T00:36:42Z\",\n      \"type\":\"Individual\"\n    },\n    \"header\": {\n      \"fromEmail\": \"apitest@qualtrics.com\",\n      \"fromName\": \"Api Tester\",\n      \"replyToEmail\": \"noreply@qualtrics.com\", \n      \"subject\": \"Example Subject\"\n    },\n    \"message\": {\n      \"libraryId\":\"UR_1M4aHozEkSxUfCl\",\n      \"messageId\":\"MS_0Vdgn7nLGSQBlYN\"\n    },\n    \"recipients\": {\n      \"mailingListId\":\"ML_01gl1yHFWKSU8y9\"\n    },\n    \"embeddedData\": {\n      \"emailAuthor\": \"carmenb\",\n      \"emailType\": \"leading question\"\n    },\n    \"sendDate\": \"2015-11-17T00:36:42Z\"\n}' 'https://yourdatacenterid.qualtrics.com/API/v3/distributions'","language":"curl","name":"cURL (w/ embeddedData)"}]},"method":"post","results":{"codes":[{"status":200,"language":"json","code":"{\n  \"result\": {\n    \"id\": \"EMD_a4y9QGA0sGBRzmt\"\n  },\n  \"meta\": {\n    \"httpStatus\": \"200 - OK\"\n  }\n}","name":""}]},"settings":"","auth":"required","params":[{"_id":"55d3a3ad0168850d0073f324","ref":"","in":"body","required":true,"desc":"Time to send the email. See [Dates and Times](doc:dates-and-times) for more information on the date and time format.","default":"","type":"datetime","name":"sendDate"},{"_id":"55d3a3ad0168850d0073f322","ref":"","in":"body","required":true,"desc":"Email from address","default":"","type":"string","name":"header[fromEmail]"},{"_id":"55d3a3ad0168850d0073f321","ref":"","in":"body","required":true,"desc":"Email from name","default":"","type":"string","name":"header[fromName]"},{"_id":"55d3a3ad0168850d0073f320","ref":"","in":"body","required":false,"desc":"Email reply-to address","default":"fromEmail","type":"string","name":"header[replyToEmail]"},{"_id":"55d3a3ad0168850d0073f31f","ref":"","in":"body","required":true,"desc":"Email subject","default":"","type":"string","name":"header[subject]"},{"_id":"55d3a3ad0168850d0073f328","ref":"","in":"body","required":true,"desc":"Mailing List ID","default":"","type":"string","name":"recipients[mailingListId]"},{"_id":"5a7227aaedf46e0012c99939","ref":"","in":"body","required":false,"desc":"The Contact ID of the contact within the Mailing List. For Target Audience users, please look at documentation below for explanation on grabbing this ID.","default":"","type":"string","name":"recipients[contactId]"},{"_id":"55d3a3ad0168850d0073f31e","ref":"","in":"body","required":true,"desc":"ID of the message. This is required in conjunction with the libraryId if no messageText is supplied.","default":"","type":"string","name":"message[messageId]"},{"_id":"57e5845f6dec2419008de60e","ref":"","in":"body","required":false,"desc":"A custom message text","default":"","type":"string","name":"message[messageText]"},{"_id":"5642709db48bdf19006a4d42","ref":"","in":"body","required":true,"desc":"Library ID of the message. This is required in conjunction with the messageId if no messageText is supplied.","default":"","type":"string","name":"message[libraryId]"},{"_id":"55d3a3ad0168850d0073f323","ref":"","in":"body","required":true,"desc":"ID of the survey to send to recipients","default":"","type":"string","name":"surveyLink[surveyId]"},{"_id":"56427ec2b65f510d0035e51e","ref":"","in":"body","required":false,"desc":"If set it will use this date as the day the distribution will expire. See [Dates and Times](doc:dates-and-times) for more information on the date and time format. If it isn't set the default expiration date for all links is 60 days.","default":"","type":"datetime","name":"surveyLink[expirationDate]"},{"_id":"56427ec2b65f510d0035e51d","ref":"","in":"body","required":false,"desc":"The type of link that will be sent out. Possible values are: [Individual, Multiple, Anonymous]. If Individual, one unique link for each recipient will be generated that can be taken one time. If Multiple, then a unique link is sent out to each recipient that can be taken multiple times. If Anonymous, then the same generic link is sent to all recipients and can be taken multiple times. Possible values are: Individual, Multiple, Anonymous","default":"Individual","type":"string","name":"surveyLink[type]"},{"_id":"5b63a466aa28650003406922","ref":"","in":"body","required":false,"desc":"Contains up to 10 subkeys. Each of these subkeys has a name, consisting of no more than 200 characters, and a value, consisting of no more than 1024 characters.","default":"","type":"object","name":"embeddedData"}],"url":"/v:version/distributions"},"isReference":false,"order":1,"body":"[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Default Expiration Date\",\n  \"body\": \"The default expiration date for all links is 60 days. You can add a custom expiration date to your survey links by the expirationDate parameter in the surveyLink object in the body of your request. Please see the cURL example.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Target Audience\",\n  \"body\": \"See [Create Survey Distribution for Target Audience](doc:ta-create-survey-distribution) for information on using this API with Target Audience. This includes using the API with transactions.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Message ID Required with a Survey Link\",\n  \"body\": \"If you use this API with a survey link, you are required to specify a message ID. To send a distribution with custom messageText, the call must not specify the surveyLink body parameter.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Distribution Embedded Data\",\n  \"body\": \"Values specified in the embeddedData parameter may be used within Distribution Reporting as a method of tagging distributions with certain values. These values are not available within the Survey Flow.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"Unfortunately this feature will not work with this API call. We recommend using Postman to test this call.\",\n  \"title\": \"Try It Out Feature Limitation\"\n}\n[/block]","excerpt":"Create a new survey distribution","slug":"create-survey-distribution","type":"endpoint","title":"Create Survey Distribution"}

postCreate Survey Distribution

Create a new survey distribution

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Body Params

sendDate:
required
datetime
Time to send the email. See [Dates and Times](doc:dates-and-times) for more information on the date and time format.
header[fromEmail]:
required
string
Email from address
header[fromName]:
required
string
Email from name
header[replyToEmail]:
stringfromEmail
Email reply-to address
header[subject]:
required
string
Email subject
recipients[mailingListId]:
required
string
Mailing List ID
recipients[contactId]:
string
The Contact ID of the contact within the Mailing List. For Target Audience users, please look at documentation below for explanation on grabbing this ID.
message[messageId]:
required
string
ID of the message. This is required in conjunction with the libraryId if no messageText is supplied.
message[messageText]:
string
A custom message text
message[libraryId]:
required
string
Library ID of the message. This is required in conjunction with the messageId if no messageText is supplied.
surveyLink[surveyId]:
required
string
ID of the survey to send to recipients
surveyLink[expirationDate]:
datetime
If set it will use this date as the day the distribution will expire. See [Dates and Times](doc:dates-and-times) for more information on the date and time format. If it isn't set the default expiration date for all links is 60 days.
surveyLink[type]:
stringIndividual
The type of link that will be sent out. Possible values are: [Individual, Multiple, Anonymous]. If Individual, one unique link for each recipient will be generated that can be taken one time. If Multiple, then a unique link is sent out to each recipient that can be taken multiple times. If Anonymous, then the same generic link is sent to all recipients and can be taken multiple times. Possible values are: Individual, Multiple, Anonymous
embeddedData:
object
Contains up to 10 subkeys. Each of these subkeys has a name, consisting of no more than 200 characters, and a value, consisting of no more than 1024 characters.

Examples


Result Format


Documentation

[block:callout] { "type": "info", "title": "Default Expiration Date", "body": "The default expiration date for all links is 60 days. You can add a custom expiration date to your survey links by the expirationDate parameter in the surveyLink object in the body of your request. Please see the cURL example." } [/block] [block:callout] { "type": "warning", "title": "Target Audience", "body": "See [Create Survey Distribution for Target Audience](doc:ta-create-survey-distribution) for information on using this API with Target Audience. This includes using the API with transactions." } [/block] [block:callout] { "type": "warning", "title": "Message ID Required with a Survey Link", "body": "If you use this API with a survey link, you are required to specify a message ID. To send a distribution with custom messageText, the call must not specify the surveyLink body parameter." } [/block] [block:callout] { "type": "info", "title": "Distribution Embedded Data", "body": "Values specified in the embeddedData parameter may be used within Distribution Reporting as a method of tagging distributions with certain values. These values are not available within the Survey Flow." } [/block] [block:callout] { "type": "warning", "body": "Unfortunately this feature will not work with this API call. We recommend using Postman to test this call.", "title": "Try It Out Feature Limitation" } [/block]

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}