Create Distribution

POST {{baseUrl}}/distributions

Create a distribution <!--From Readme--> <!-- theme: info -->

Note

You can send a distribution to a:

• single contact
• mailing list
• transaction BatchId

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

Results in:

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

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 Body

{"message"=>{"libraryId"=>"UR_1M4aHozEkSxUfCl", "messageId"=>"MS_0Vdgn7nLGSQBlYN", "messageText"=>"Example Message Text"}, "recipients"=>{"mailingListId"=>"CG_012345678901234", "contactId"=>"CGC_012345678901234", "transactionBatchId"=>"BT_ZZZZ45678901234"}, "header"=>{"fromEmail"=>"apiexample@qualtrics.com", "fromName"=>"Test Name", "subject"=>"Example Subject", "replyToEmail"=>"apiexample@qualtrics.com"}, "surveyLink"=>{"surveyId"=>"SV_cHbKMOdeT8NetF3", "expirationDate"=>"2021-12-20T00:21:58.532Z", "type"=>"Anonymous"}, "sendDate"=>"1985-06-25T06:59:58.016Z", "embeddedData"=>{"utf"=>"enim tempor ad"}}

HEADERS

RESPONSES

status: OK

{"result":{"id":"EMD_1234567890abcde"},"meta":{"httpStatus":"Excepteur id amet cupidatat nulla","requestId":"in ullamco tempor incididunt","notice":"incididunt in occaecat Duis in"}}