{"_id":"5a7b7a5616354100121aef12","project":"55843604fd8d910d007b9502","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"},"category":{"_id":"5a2af4a1bc5fba00283909c1","project":"55843604fd8d910d007b9502","version":"558444ceafccfd0d00fcb2bb","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-12-08T20:22:57.771Z","from_sync":false,"order":40,"slug":"target-audience-distributions","title":"iQ Directory Distributions"},"user":"5919f13aff66b00f00f1948c","githubsync":"","__v":14,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-02-07T22:14:46.671Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{\n  \"result\": {\n    \"id\": \"EMD_a4y9QGA0sGBRzmt\"\n  },\n  \"meta\": {\n    \"httpStatus\": \"200 - OK\"\n  }\n}","name":""}]},"method":"post","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\":\"CG_01gl1yHFWKSU8y9\"\n    },\n    \"sendDate\": \"2015-11-17T00:36:42Z\"\n}' 'https://yourdatacenterid.qualtrics.com/API/v3/distributions'","name":"cURL (w/ mailingListId)"},{"name":"cURL (w/ transactionId)","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@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\":\"CG_01gl1yHFWKSU8y9\",\n      \"transactionId\":\"CTR_012345678901234\"\n    },\n    \"sendDate\": \"2015-11-17T00:36:42Z\"\n}' 'https://yourdatacenterid.qualtrics.com/API/v3/distributions'"},{"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@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\":\"CG_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/ embedded data)"}]},"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":"582e16c7d3eaed0f002e4da5","ref":"","in":"body","required":false,"desc":"Transactions are only usable by Target Audience users. You cannot provide both a **transactionId** and a **contactId**.","default":"","type":"string","name":"recipients[transactionId]"},{"_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":"5b63a2f3aa28650003406921","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":0,"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\": \"info\",\n  \"title\": \"Target Audience - Distributing Surveys to Individual Contacts\",\n  \"body\": \"Each contact in Target Audience can have different IDs. A contact always has a Directory Level Contact ID (for example, **CID_012345678901234**). \\n\\nIf a contact is added to a mailing list, it is given a contact lookup ID (for example, **CGC_012345678901234**). This ID can be found using the [Get Directory Contact API](https://api.qualtrics.com/docs/get-directory-contact) API or the [Get Contact in Mailing List](https://api.qualtrics.com/docs/get-contact-in-mailing-list) API, as the ** contactLookupId** key. This contact lookup ID is the Contact ID value you pass as the **contactId** parameter. \\n\\nIf a [transaction is created for a contact](https://api.qualtrics.com/docs/using-transactions-in-target-audience) then the contact has a given Transaction ID (for example, **CTR_012345678901234**). You would pass this value in for the **transactionId** parameter. \\n\\nYou can only pass in a **transactionId** or a **contactId**, you cannot pass in both.\"\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":"ta-create-survey-distribution","type":"endpoint","title":"Create Survey Distribution for Target Audience"}

postCreate Survey Distribution for Target Audience

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.
recipients[transactionId]:
string
Transactions are only usable by Target Audience users. You cannot provide both a **transactionId** and a **contactId**.
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": "info", "title": "Target Audience - Distributing Surveys to Individual Contacts", "body": "Each contact in Target Audience can have different IDs. A contact always has a Directory Level Contact ID (for example, **CID_012345678901234**). \n\nIf a contact is added to a mailing list, it is given a contact lookup ID (for example, **CGC_012345678901234**). This ID can be found using the [Get Directory Contact API](https://api.qualtrics.com/docs/get-directory-contact) API or the [Get Contact in Mailing List](https://api.qualtrics.com/docs/get-contact-in-mailing-list) API, as the ** contactLookupId** key. This contact lookup ID is the Contact ID value you pass as the **contactId** parameter. \n\nIf a [transaction is created for a contact](https://api.qualtrics.com/docs/using-transactions-in-target-audience) then the contact has a given Transaction ID (for example, **CTR_012345678901234**). You would pass this value in for the **transactionId** parameter. \n\nYou can only pass in a **transactionId** or a **contactId**, you cannot pass in both." } [/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 }}