Create Distribution
POST/distributions
Create a distribution
You can send a distribution to a:
- single contact
- mailing list
- transaction BatchId
All requests require both the mailingListId and contactId properties.
Create Distribution
To create a distribution using an existing message id from one of your libraries, you can make a call like this:
curl -XPOST -H 'X-API-TOKEN: <API Key>' -H 'Content-Type: application/json' https://co1.qualtrics.com/API/v3/distributions -d '{
"message": {
"libraryId": "UR_8cRedheujEbcxgN",
"messageId": "MS_1Mt2Nj5kczdnjMh"
},
"recipients": {
"mailingListId": "CG_6F1gRt186CZOVoh",
"directoryId": "POOL_2t0pE8tJnEEmgD3"
},
"header": {
"fromName": "Qualtrics",
"replyToEmail": "noreply@qualtrics.com",
"fromEmail": "noreply@qualtrics.com",
"subject": "Survey Distribution"
},
"surveyLink": {
"surveyId": "SV_ebdf20QralHTzQF",
"expirationDate": "2019-09-13T00:00:00Z",
"type": "Individual"
},
"sendDate": "2018-12-04T11:13:35Z"
}'
The result of the call will look like this, and success indicates the distribution was sent:
{
"result": {"id": "EMD_4OQ4N84KC82cfaV"},
"meta": {"httpStatus": "200 - OK",
"requestId": "9d6b8cc4-2f84-4b28-970b-84501d180bdd"
}
}
Generate Distribution Links
Here is the second use of this API endpoint, which is to generate survey links but not send them out. The body parameters are different, as shown in this example.
curl -XPOST -H "X-API-TOKEN: <API Key>" -H "Content-Type: application/json" https://env.qualtrics.com/API/v3/distributions -d '{
"surveyId": "SV_6hsqQZccKfnIKGN",
"linkType": "Individual",
"description": "distribution 2019-06-24 00:00:00",
"action": "CreateDistribution",
"expirationDate": "2023-09-13T06:00:00Z",
"mailingListId": "CG_6F1gRt186CZOVoh",
"directoryId": "POOL_2t0pE8tJnEEmgD3"
}'
Results in:
{
"result": {
"id": "EMD_HqyMlaZufKzJvMc"
},
"meta": {
"httpStatus": "200 - OK",
"requestId": "dabfa3fc-c52c-4102-b64e-fc45e3a26cee"
}
}
Don't try to use this to send a reminder to a single contact as you cannot put both a transaction ID and transaction batch ID into the recipients.
In other words, this call:
*"recipients": {
"transactionBatchId": "BT_bJkDYS0hp07Z35X",
"transactionId": "CTR_7aMCCfUTfIK8vkx"
},
will produce this error:
{
"httpStatus": "400 - Bad Request",
"error": {
"errorMessage": "Cannot provide recipients[contactId], recipients[sampleId], or recipients[transactionId] if recipients[transactionBatchId] is specified.",
"errorCode": "DRD_0.1"
}
}
You can only send a distribution list to a single contact within a mailing list, otherwise, you cannot send a distribution list to a single contact.
Retrieve Generated Links
Having generated the links, here is how you retrieve them.
curl -XGET -H "X-API-TOKEN: <API Key>" https://co1.qualtrics.com/API/v3/distributions/EMD_HqyMlaZufKzJvMc/links?surveyId=SV_6hsqQZccKfnIKGN
Results in:
{
"result": {
"elements": [
{
"contactId": "CID_8DiYav1l32jNdFb",
"link": "https://apidocs.iad1.qualtrics.com/SE?Q_DL=HqyMlaZufKzJvMc_6hsqQZccKfnIKGN_CGC_8cshsoUZNmeE5JX",
"exceededContactFrequency": false,
"linkExpiration": "2019-07-24T06:00:00Z",
"status": "Email not sent",
"lastName": "Aynchmkx",
"firstName": "Asyncpgcgwjk",
"externalDataReference": "AsyncpgcgwjkAynchmkx@qualtrics.com",
"email": "AsyncpgcgwjkAynchmkx@qualtrics.com",
"phone": "123-456-7890",
"unsubscribed": false
}
]
}
},
...
Generate Links for Transaction Batch
When generating links (but not sending emails) for a transaction batch through the Create Distribution API, you must include the "action": "CreateTransactionBatchDistribution" property in the request.
This example request uses the property "action": "CreateTransactionBatchDistribution" to generate links for a transaction batch.
{
"surveyId": "SV_2ufiCBrlEIMdHAq",
"linkType": "Individual",
"description": "distribution 2022-03-24 00:00:00",
"action": "CreateTransactionBatchDistribution",
"expirationDate": "2022-07-24T00:00:00Z",
"transactionBatchId": "BT_29mDeWdhdsmOVnk",
"directoryId": "POOL_2t0pE8tJnEEmgD3"
}
You can find more on creating distributions in this guide.
Note that this API will work with Research Core as well.
Request
Responses
- 200
- 400
- 401
- default
Successful Create Distribution response
Invalid arguments response
Unauthorized
A default error response