{"_id":"599c7133033797000fa2cb5e","project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":67,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"category":{"_id":"599c6da8f180820025f14909","project":"55843604fd8d910d007b9502","version":"558444ceafccfd0d00fcb2bb","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-08-22T17:45:12.239Z","from_sync":false,"order":3,"slug":"transactions","title":"Transactions in Target Audience"},"user":"5919f13aff66b00f00f1948c","githubsync":"","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-22T18:00:19.051Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"This tutorial describes how to use transactions in Target Audience. Transactions allow you to track interactions with your customers and save data with each interaction that can be referenced later in a survey. For example, with every purchase, you could save a customer's purchase amount and location and distribute surveys that are customized based on this transaction data.\n\nTransaction data can be accessed in surveys the same way as embedded data. See [Embedded Data](https://www.qualtrics.com/support/survey-platform/survey-module/survey-flow/standard-elements/embedded-data/) for more information.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Target Audience Only\",\n  \"body\": \"These APIs are only available to Target Audience users.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Transaction Objects\"\n}\n[/block]\nThere are two objects required when working with transactions: a *contact transaction* (or just a transaction) and a *transaction batch*.\n\n## Contact Transaction\n\nA contact transaction is the transaction data associated with a contact. It consists of key-value pairs that specify the information you want to associate with a transaction and the date and time the transaction occurred. You can set the transaction date and time to any time (so you can batch transactions at the end of the day, for instance).\n\nThe following shows an example transaction associated with a contact and mailing list. Transactions are always associated with a contact and a mailing list (and the contact has to be in the specified mailing list). The key-value pairs in the **data** object are the transaction data that was associated with the contact. In a survey, each item can be used as embedded data. For instance, the survey could have a condition to display a block only appear if **enrolledInValueClub** is equal to **true**.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"String Values\",\n  \"body\": \"All values in the transaction are string values. Numbers are converted to strings. Boolean values are converted to the strings **true** or **false**.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"contactId\\\": \\\"CID_123456\\\",\\n\\t\\\"data\\\": {\\n\\t\\t\\\"currency\\\": \\\"Euro\\\",\\n\\t\\t\\\"spending\\\": 21.45,\\n\\t\\t\\\"type\\\": \\\"Online\\\",\\n    \\\"representative\\\": \\\"B. Smith\\\",\\n    \\\"enrolledInValueClub\\\": true\\n\\t},\\n\\t\\\"mailingListId\\\": \\\"CG_1234567\\\",\\n\\t\\\"transactionDate\\\": \\\"2017-08-18 20:51:00\\\",\\n\\t\\\"transactionId\\\": \\\"CTR_12345678\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Contact Transaction\"\n    }\n  ]\n}\n[/block]\n## Transaction Batch\n\nA transaction batch collects all of the transactions that are relevant to the survey you will send out. Because contacts can have multiple transactions (and thus multiple data items with the same keys), transaction batches allow you to specify which transaction will be available to the survey as embedded data.\n\nA transaction batch is an array of transactions. The following shows an example of a transaction batch:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"transactionIds\\\": [\\n\\t\\t\\\"CTR_12345\\\",\\n\\t\\t\\\"CTR_23461\\\",\\n\\t\\t\\\"CTR_47113\\\",\\n\\t],\\n\\t\\\"creationDate\\\": \\\"2017-08-28 21:30:00\\\"\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Transaction Batch\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Overview of the Steps\"\n}\n[/block]\nThe following three steps show how to create a transaction and then send an email distribution. The first step uses the [Create Contact Transactions](doc:create-contact-transactions)  API and associates transaction data with a contact. The second step uses the [Create Transaction Batch](doc:create-transaction-batch) API to collect the relevant transactions into a batch. Finally, the third step uses the [Create Transaction Batch Survey Distribution](doc:create-transaction-batch-survey-distribution) API to generate a distribution to the contacts associated with the transactions in the specified transaction batch.\n[block:api-header]\n{\n  \"title\": \"Step One: Create Transaction\"\n}\n[/block]\nThe following code sample creates three transactions associated with three different contacts. Note that a mailing list ID is required, and if a contact is not on the specified mailing list, you will get an error.\n\nThe code sample creates three transactions associated with three users. All are simply a **location** value. Note that they are given arbitrary keys: **a**, **b**, and **c**. Also, note that the transaction date we are using is different with each transaction.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Transaction Date\",\n  \"body\": \"The **transactionDate** parameter must match the format in the example exactly. It must be UTC, must include seconds, must be 24-hour time, and must have a space between the date and time.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create Contact Transaction\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions\\\".format(dataCenter, directoryId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\n\\ndata = {\\n      \\\"a\\\": {\\n\\t      \\\"mailingListId\\\": \\\"CG_1234\\\",\\n        \\\"contactId\\\": \\\"CID_12345\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-21 12:00:00\\\",\\n        \\\"data\\\": {\\n\\t\\t        \\\"location\\\": \\\"Seattle\\\"\\n        }\\n      },\\n      \\\"b\\\": {\\n        \\\"mailingListId\\\": \\\"CG_1234\\\",\\n        \\\"contactId\\\": \\\"CID_84312\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-22 14:00:00\\\",\\n        \\\"data\\\": {\\n\\t          \\\"location\\\": \\\"New York\\\"\\n        }\\n\\n      },\\n      \\\"c\\\": {\\n        \\\"mailingListId\\\": \\\"CG_1234\\\",\\n        \\\"contactId\\\": \\\"CID_67341\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-23 10:00:00\\\",\\n        \\\"data\\\": {\\n            \\\"location\\\": \\\"Chicago\\\"\\n        }\\n      }\\n   }\\n\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe response to this code snippet indicates the transaction IDs:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"d97b2b51-acbe-4dae-afdb-1f1055fea781\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"createdTransactions\\\": {\\n            \\\"a\\\": {\\n                \\\"id\\\": \\\"CTR_12345\\\"\\n            },\\n            \\\"b\\\": {\\n                \\\"id\\\": \\\"CTR_12346\\\"\\n            },\\n            \\\"c\\\": {\\n                \\\"id\\\": \\\"CTR_12347\\\"\\n            }\\n        },\\n        \\\"unprocessedTransactions\\\": {}\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe transaction IDs need to be extracted from the response object and used to create a transaction batch, the next step.\n[block:api-header]\n{\n  \"title\": \"Step Two: Create a Transaction Batch\"\n}\n[/block]\nThe transaction batch selects the transactions to be surfaced to the survey as embedded data. The batch is used to create a distribution for requesting responses to the survey.\n\nThe following example shows how to create a transaction batch comprised of the three transactions that were created in the previous step:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create Transaction Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches\\\".format(dataCenter, directoryId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n\\t\\\"transactionIds\\\": [\\n\\t\\t\\\"CTR_12345\\\",\\n\\t\\t\\\"CTR_12346\\\",\\n\\t\\t\\\"CTR_12347\\\",\\n\\t],\\n\\t\\\"creationDate\\\": \\\"2017-08-28 21:30:00\\\"\\n   }\\n\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe response object contains the transaction batch ID, as shown in the following response:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"2f9aff75-d7a0-4462-bb69-80a345f5b82a\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"id\\\": \\\"BT_12345\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe transaction batch ID will be used in the next step to create an email distribution.\n[block:api-header]\n{\n  \"title\": \"Step Three: Create a Distribution\"\n}\n[/block]\nYou can now distribute your survey to the contacts with transaction data. There is no UI to create a transaction distribution.\n\nA transaction distribution requires several pieces of information: You need the transaction batch ID from the previous step. You need the survey ID for the survey to be sent. You need to create a survey invitation message.\n\nBefore beginning:\n\n1. Create a message and save it in your library.\n2. Obtain the message ID and your library ID.\n3. Obtain the survey's ID.\n\nTo create a message, see [Creating a Message in a Library](https://www.qualtrics.com/support/survey-platform/account-library/message-library#CreatingAMessageInALibrary). You need to obtain your message's ID and the library's ID. See [Finding Your Qualtrics IDs](doc:finding-qualtrics-ids) for more information.\n\nReplace the values in the **data** object below. The **transactionBatchId** was obtained in the last step. You also need to set an expiration date for the link to your survey as **expirationDate**. Finally, set the **sendDate** to the date and time the invitation should be delivered. Both of these dates follow the ISO 8601 format. See [Dates and Times](doc:dates-and-times) for more information.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create Transaction Batch Survey Distribution\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/distributions\\\".format(dataCenter)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n    \\\"surveyLink\\\": {\\n      \\\"surveyId\\\":\\\"SV_12345\\\",\\n      \\\"expirationDate\\\":\\\"2017-08-31T00:00:00Z\\\",\\n      \\\"type\\\":\\\"Individual\\\"\\n    },\\n    \\\"header\\\": {\\n      \\\"fromEmail\\\": \\\"noreply:::at:::qemailserver.com\\\",\\n      \\\"fromName\\\": \\\"Survey User\\\",\\n      \\\"replyToEmail\\\": \\\"noreply@qualtrics.com\\\", \\n      \\\"subject\\\": \\\"Transaction Test\\\"\\n    },\\n    \\\"message\\\": {\\n      \\\"libraryId\\\":\\\"UR_123456\\\",\\n      \\\"messageId\\\":\\\"MS_123456\\\"\\n    },\\n    \\\"recipients\\\": {\\n      \\\"transactionBatchId\\\":\\\"BT_12345\\\"\\n    },\\n    \\\"sendDate\\\": \\\"2017-08-17T22:20:00Z\\\"\\n\\n   }\\n\\n\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nNote that the recipients are selected by the transaction batch rather than a mailing list.\n\nThe response object contains the distribution's ID as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"88f4f662-e42b-40aa-bc0e-ec4afec0016f\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"id\\\": \\\"EMD_12345\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe transaction distribution appears in the administration UI as a new distribution with the contact list as the transaction batch:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/e98aefb-Distribute_Survey___Qualtrics_Survey_Software.png\",\n        \"Distribute Survey _ Qualtrics Survey Software.png\",\n        1275,\n        942,\n        \"#e9ecf2\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Conflicting Transactions\"\n}\n[/block]\nBecause each contact can contain multiple transactions, it is possible for there to be conflicting transactions. If there is a conflict, the last transaction in the transaction batch wins.\n\nFor instance, if a contact has these two transactions:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n\\t{\\n\\t\\t\\\"contactId\\\": \\\"CID_1\\\",\\n\\t\\t\\\"data\\\": {\\n\\t\\t\\t\\\"location\\\": \\\"Seattle\\\"\\n\\t\\t},\\n\\t\\t\\\"id\\\": \\\"CTR_1\\\",\\n\\t\\t\\\"mailingListId\\\": \\\"CG_1\\\",\\n\\t\\t\\\"transactionDate\\\": 1504283255000\\n\\t},\\n\\t{\\n\\t\\t\\\"contactId\\\": \\\"CID_1\\\",\\n\\t\\t\\\"data\\\": {\\n\\t\\t\\t\\\"location\\\": \\\"London\\\"\\n\\t\\t},\\n\\t\\t\\\"id\\\": \\\"CTR_2\\\",\\n\\t\\t\\\"mailingListId\\\": \\\"CG_1\\\",\\n\\t\\t\\\"transactionDate\\\": 1503943200000\\n\\t},\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nBoth transactions contain a **location** item, but that in itself does not cause a conflict. In fact, a contact with multiple transactions with the same-named data items is normal. \n\nThe conflict occurs if the transaction batch references two (or more) transactions in the same contact. For instance, this transaction batch references these two transactions with the second transaction (**CTR_2**) coming last in the batch:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"transactionIds\\\": [\\n\\t\\t\\\"CTR_1\\\",\\n\\t\\t\\\"CTR_2\\\",\\n\\t],\\n\\t\\\"creationDate\\\": \\\"2017-08-28 21:30:00\\\"\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe survey could reference the **location** transaction data item as piped text, as highlighted below:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0dff188-Travel_Survey_Question.png\",\n        \"Travel Survey Question.png\",\n        1275,\n        753,\n        \"#f7f8f9\"\n      ]\n    }\n  ]\n}\n[/block]\nIn this case, the survey would display **London** because it is the last transaction in the transaction batch:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/bbf340c-London.png\",\n        \"London.png\",\n        1828,\n        766,\n        \"#f3f3f3\"\n      ]\n    }\n  ]\n}\n[/block]\nIf the transactions are reversed in the transaction batch as shown below the piped text would refer to a different transaction:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"transactionIds\\\": [\\n\\t\\t\\\"CTR_2\\\",\\n\\t\\t\\\"CTR_1\\\",\\n\\t],\\n\\t\\\"creationDate\\\": \\\"2017-08-28 21:30:00\\\"\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nBecause the last transaction refers to the **Seattle** location, the survey would display **Seattle** as the piped text:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/b61539d-Seattle.png\",\n        \"Seattle.png\",\n        1828,\n        766,\n        \"#f3f3f3\"\n      ]\n    }\n  ]\n}\n[/block]","excerpt":"A tutorial for getting started with transactions in Target Audience","slug":"using-transactions-in-target-audience","type":"basic","title":"Using Transactions in Target Audience"}

Using Transactions in Target Audience

A tutorial for getting started with transactions in Target Audience

This tutorial describes how to use transactions in Target Audience. Transactions allow you to track interactions with your customers and save data with each interaction that can be referenced later in a survey. For example, with every purchase, you could save a customer's purchase amount and location and distribute surveys that are customized based on this transaction data. Transaction data can be accessed in surveys the same way as embedded data. See [Embedded Data](https://www.qualtrics.com/support/survey-platform/survey-module/survey-flow/standard-elements/embedded-data/) for more information. [block:callout] { "type": "warning", "title": "Target Audience Only", "body": "These APIs are only available to Target Audience users." } [/block] [block:api-header] { "title": "Transaction Objects" } [/block] There are two objects required when working with transactions: a *contact transaction* (or just a transaction) and a *transaction batch*. ## Contact Transaction A contact transaction is the transaction data associated with a contact. It consists of key-value pairs that specify the information you want to associate with a transaction and the date and time the transaction occurred. You can set the transaction date and time to any time (so you can batch transactions at the end of the day, for instance). The following shows an example transaction associated with a contact and mailing list. Transactions are always associated with a contact and a mailing list (and the contact has to be in the specified mailing list). The key-value pairs in the **data** object are the transaction data that was associated with the contact. In a survey, each item can be used as embedded data. For instance, the survey could have a condition to display a block only appear if **enrolledInValueClub** is equal to **true**. [block:callout] { "type": "info", "title": "String Values", "body": "All values in the transaction are string values. Numbers are converted to strings. Boolean values are converted to the strings **true** or **false**." } [/block] [block:code] { "codes": [ { "code": "{\n\t\"contactId\": \"CID_123456\",\n\t\"data\": {\n\t\t\"currency\": \"Euro\",\n\t\t\"spending\": 21.45,\n\t\t\"type\": \"Online\",\n \"representative\": \"B. Smith\",\n \"enrolledInValueClub\": true\n\t},\n\t\"mailingListId\": \"CG_1234567\",\n\t\"transactionDate\": \"2017-08-18 20:51:00\",\n\t\"transactionId\": \"CTR_12345678\"\n}", "language": "json", "name": "Contact Transaction" } ] } [/block] ## Transaction Batch A transaction batch collects all of the transactions that are relevant to the survey you will send out. Because contacts can have multiple transactions (and thus multiple data items with the same keys), transaction batches allow you to specify which transaction will be available to the survey as embedded data. A transaction batch is an array of transactions. The following shows an example of a transaction batch: [block:code] { "codes": [ { "code": "{\n\t\"transactionIds\": [\n\t\t\"CTR_12345\",\n\t\t\"CTR_23461\",\n\t\t\"CTR_47113\",\n\t],\n\t\"creationDate\": \"2017-08-28 21:30:00\"\n}\n", "language": "json", "name": "Transaction Batch" } ] } [/block] [block:api-header] { "title": "Overview of the Steps" } [/block] The following three steps show how to create a transaction and then send an email distribution. The first step uses the [Create Contact Transactions](doc:create-contact-transactions) API and associates transaction data with a contact. The second step uses the [Create Transaction Batch](doc:create-transaction-batch) API to collect the relevant transactions into a batch. Finally, the third step uses the [Create Transaction Batch Survey Distribution](doc:create-transaction-batch-survey-distribution) API to generate a distribution to the contacts associated with the transactions in the specified transaction batch. [block:api-header] { "title": "Step One: Create Transaction" } [/block] The following code sample creates three transactions associated with three different contacts. Note that a mailing list ID is required, and if a contact is not on the specified mailing list, you will get an error. The code sample creates three transactions associated with three users. All are simply a **location** value. Note that they are given arbitrary keys: **a**, **b**, and **c**. Also, note that the transaction date we are using is different with each transaction. [block:callout] { "type": "info", "title": "Transaction Date", "body": "The **transactionDate** parameter must match the format in the example exactly. It must be UTC, must include seconds, must be 24-hour time, and must have a space between the date and time." } [/block] [block:code] { "codes": [ { "code": "# Create Contact Transaction\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions\".format(dataCenter, directoryId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\n\ndata = {\n \"a\": {\n\t \"mailingListId\": \"CG_1234\",\n \"contactId\": \"CID_12345\",\n \"transactionDate\": \"2017-08-21 12:00:00\",\n \"data\": {\n\t\t \"location\": \"Seattle\"\n }\n },\n \"b\": {\n \"mailingListId\": \"CG_1234\",\n \"contactId\": \"CID_84312\",\n \"transactionDate\": \"2017-08-22 14:00:00\",\n \"data\": {\n\t \"location\": \"New York\"\n }\n\n },\n \"c\": {\n \"mailingListId\": \"CG_1234\",\n \"contactId\": \"CID_67341\",\n \"transactionDate\": \"2017-08-23 10:00:00\",\n \"data\": {\n \"location\": \"Chicago\"\n }\n }\n }\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The response to this code snippet indicates the transaction IDs: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"d97b2b51-acbe-4dae-afdb-1f1055fea781\"\n },\n \"result\": {\n \"createdTransactions\": {\n \"a\": {\n \"id\": \"CTR_12345\"\n },\n \"b\": {\n \"id\": \"CTR_12346\"\n },\n \"c\": {\n \"id\": \"CTR_12347\"\n }\n },\n \"unprocessedTransactions\": {}\n }\n}", "language": "json", "name": "Response" } ] } [/block] The transaction IDs need to be extracted from the response object and used to create a transaction batch, the next step. [block:api-header] { "title": "Step Two: Create a Transaction Batch" } [/block] The transaction batch selects the transactions to be surfaced to the survey as embedded data. The batch is used to create a distribution for requesting responses to the survey. The following example shows how to create a transaction batch comprised of the three transactions that were created in the previous step: [block:code] { "codes": [ { "code": "# Create Transaction Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches\".format(dataCenter, directoryId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n\t\"transactionIds\": [\n\t\t\"CTR_12345\",\n\t\t\"CTR_12346\",\n\t\t\"CTR_12347\",\n\t],\n\t\"creationDate\": \"2017-08-28 21:30:00\"\n }\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The response object contains the transaction batch ID, as shown in the following response: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"2f9aff75-d7a0-4462-bb69-80a345f5b82a\"\n },\n \"result\": {\n \"id\": \"BT_12345\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The transaction batch ID will be used in the next step to create an email distribution. [block:api-header] { "title": "Step Three: Create a Distribution" } [/block] You can now distribute your survey to the contacts with transaction data. There is no UI to create a transaction distribution. A transaction distribution requires several pieces of information: You need the transaction batch ID from the previous step. You need the survey ID for the survey to be sent. You need to create a survey invitation message. Before beginning: 1. Create a message and save it in your library. 2. Obtain the message ID and your library ID. 3. Obtain the survey's ID. To create a message, see [Creating a Message in a Library](https://www.qualtrics.com/support/survey-platform/account-library/message-library#CreatingAMessageInALibrary). You need to obtain your message's ID and the library's ID. See [Finding Your Qualtrics IDs](doc:finding-qualtrics-ids) for more information. Replace the values in the **data** object below. The **transactionBatchId** was obtained in the last step. You also need to set an expiration date for the link to your survey as **expirationDate**. Finally, set the **sendDate** to the date and time the invitation should be delivered. Both of these dates follow the ISO 8601 format. See [Dates and Times](doc:dates-and-times) for more information. [block:code] { "codes": [ { "code": "# Create Transaction Batch Survey Distribution\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/distributions\".format(dataCenter)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n \"surveyLink\": {\n \"surveyId\":\"SV_12345\",\n \"expirationDate\":\"2017-08-31T00:00:00Z\",\n \"type\":\"Individual\"\n },\n \"header\": {\n \"fromEmail\": \"noreply@qemailserver.com\",\n \"fromName\": \"Survey User\",\n \"replyToEmail\": \"noreply@qualtrics.com\", \n \"subject\": \"Transaction Test\"\n },\n \"message\": {\n \"libraryId\":\"UR_123456\",\n \"messageId\":\"MS_123456\"\n },\n \"recipients\": {\n \"transactionBatchId\":\"BT_12345\"\n },\n \"sendDate\": \"2017-08-17T22:20:00Z\"\n\n }\n\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] Note that the recipients are selected by the transaction batch rather than a mailing list. The response object contains the distribution's ID as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"88f4f662-e42b-40aa-bc0e-ec4afec0016f\"\n },\n \"result\": {\n \"id\": \"EMD_12345\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The transaction distribution appears in the administration UI as a new distribution with the contact list as the transaction batch: [block:image] { "images": [ { "image": [ "https://files.readme.io/e98aefb-Distribute_Survey___Qualtrics_Survey_Software.png", "Distribute Survey _ Qualtrics Survey Software.png", 1275, 942, "#e9ecf2" ] } ] } [/block] [block:api-header] { "title": "Conflicting Transactions" } [/block] Because each contact can contain multiple transactions, it is possible for there to be conflicting transactions. If there is a conflict, the last transaction in the transaction batch wins. For instance, if a contact has these two transactions: [block:code] { "codes": [ { "code": "[\n\t{\n\t\t\"contactId\": \"CID_1\",\n\t\t\"data\": {\n\t\t\t\"location\": \"Seattle\"\n\t\t},\n\t\t\"id\": \"CTR_1\",\n\t\t\"mailingListId\": \"CG_1\",\n\t\t\"transactionDate\": 1504283255000\n\t},\n\t{\n\t\t\"contactId\": \"CID_1\",\n\t\t\"data\": {\n\t\t\t\"location\": \"London\"\n\t\t},\n\t\t\"id\": \"CTR_2\",\n\t\t\"mailingListId\": \"CG_1\",\n\t\t\"transactionDate\": 1503943200000\n\t},\n]", "language": "json" } ] } [/block] Both transactions contain a **location** item, but that in itself does not cause a conflict. In fact, a contact with multiple transactions with the same-named data items is normal. The conflict occurs if the transaction batch references two (or more) transactions in the same contact. For instance, this transaction batch references these two transactions with the second transaction (**CTR_2**) coming last in the batch: [block:code] { "codes": [ { "code": "{\n\t\"transactionIds\": [\n\t\t\"CTR_1\",\n\t\t\"CTR_2\",\n\t],\n\t\"creationDate\": \"2017-08-28 21:30:00\"\n}\n", "language": "json" } ] } [/block] The survey could reference the **location** transaction data item as piped text, as highlighted below: [block:image] { "images": [ { "image": [ "https://files.readme.io/0dff188-Travel_Survey_Question.png", "Travel Survey Question.png", 1275, 753, "#f7f8f9" ] } ] } [/block] In this case, the survey would display **London** because it is the last transaction in the transaction batch: [block:image] { "images": [ { "image": [ "https://files.readme.io/bbf340c-London.png", "London.png", 1828, 766, "#f3f3f3" ] } ] } [/block] If the transactions are reversed in the transaction batch as shown below the piped text would refer to a different transaction: [block:code] { "codes": [ { "code": "{\n\t\"transactionIds\": [\n\t\t\"CTR_2\",\n\t\t\"CTR_1\",\n\t],\n\t\"creationDate\": \"2017-08-28 21:30:00\"\n}\n", "language": "json" } ] } [/block] Because the last transaction refers to the **Seattle** location, the survey would display **Seattle** as the piped text: [block:image] { "images": [ { "image": [ "https://files.readme.io/b61539d-Seattle.png", "Seattle.png", 1828, 766, "#f3f3f3" ] } ] } [/block]