Skip to main content

Create Distribution

POST 

/distributions

Create a distribution

Note

You can send a distribution to a:

  • single contact
  • mailing list
  • transaction BatchId
Include both Mailing List ID and Contact ID

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"
}
}

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.

json generate links

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:

json results

{
"result": {
"id": "EMD_HqyMlaZufKzJvMc"
},
"meta": {
"httpStatus": "200 - OK",
"requestId": "dabfa3fc-c52c-4102-b64e-fc45e3a26cee"
}
}
Note: This API will Send the Distribution to everyone in the Transaction Batch

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"
}
}
Note: You Can Only Send a Distribution List to a Single Contact Within A Mailing List

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.

Having generated the links, here is how you retrieve them.

json generate links

curl -XGET -H "X-API-TOKEN: <API Key>" https://co1.qualtrics.com/API/v3/distributions/EMD_HqyMlaZufKzJvMc/links?surveyId=SV_6hsqQZccKfnIKGN

Results in:

json response

{
"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
}
]
}
},

...

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.

JSON example

{
"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"
}
Additional Info

You can find more on creating distributions in this guide.

Research Core

Note that this API will work with Research Core as well.

Request​

Responses​

Successful Create Distribution response