{"_id":"59adc4cd1123e60019b63551","project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":66,"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"],"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","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-09-04T21:25:33.803Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"*Transaction batches* group transactions for use with distributions; a *batch* or *transaction batch* is required to create a transaction batch survey distribution. The APIs discussed in this guide allow you to manage your transaction batches.\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]\nThe following APIs are discussed:\n\n- [Get Transaction Batches in Directory](#get-transaction-batches-in-directory)\n- [Get Transactions in a Batch](#get-transactions-in-a-batch)\n- [Get Transaction Batch](#get-transaction-batch)\n- [Create Transaction Batch](#create-transaction-batch)\n- [Update Transaction Batch](#update-transaction-batch)\n- [Delete Transaction Batch](#delete-transaction-batch)\n- [Add Transactions to a Batch](#add-transactions-to-a-batch)\n- [Remove Transaction from a Batch](#remove-transaction-from-a-batch)\n[block:api-header]\n{\n  \"title\": \"Get Transaction Batches in Directory\"\n}\n[/block]\nThe Get Transaction Batches in Directory API returns the batch ID and creation date for all of the transaction batches in the organization's Target Audience directory.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Transaction Batches in a Directory\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches\\\".format(dataCenter, directoryId)\\nheaders = {\\n    \\\"content-type\\\": \\\"application/json\\\",\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows the transaction batch information in the **elements** array. Each result contains the batch's ID and its creation date:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"ed9e81ee-6b2b-4ec2-9bef-4aac7cc1cd08\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"batchId\\\": \\\"BT_123456\\\",\\n                \\\"creationDate\\\": \\\"2017-10-02 20:15:00\\\"\\n            },\\n            {\\n                \\\"batchId\\\": \\\"BT_123457\\\",\\n                \\\"creationDate\\\": \\\"2017-10-02 21:30:00\\\"\\n            },\\n            {\\n                \\\"batchId\\\": \\\"BT_123458\\\",\\n                \\\"creationDate\\\": \\\"2017-10-02 21:30:00\\\"\\n            },\\n            {\\n                \\\"batchId\\\": \\\"BT_123459\\\",\\n                \\\"creationDate\\\": \\\"2017-10-03 01:00:00\\\"\\n            },\\n            {\\n                \\\"batchId\\\": \\\"BT_123470\\\",\\n                \\\"creationDate\\\": \\\"2017-10-04 01:00:00\\\"\\n            }\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe **elements** array contains descriptions of each transaction batch as shown below:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**batchId**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**creationDate**\",\n    \"1-1\": \"String\",\n    \"0-2\": \"The transaction batch ID.\",\n    \"1-2\": \"The date and time the specified transaction batch was created in **yyyy-MM-dd HH:mm:ss** format.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Get Transactions in a Batch\"\n}\n[/block]\nThe Get Transactions in a Batch API returns information for each transaction in a transaction batch. The information includes the contact ID associated with the transaction, the date the transaction was added to the transaction batch, and the transaction ID.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Transactions in a Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ntransactionBatchId = \\\"BT_1234\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}/transactions\\\".format(dataCenter, directoryId, transactionBatchId)\\nheaders = {\\n    \\\"content-type\\\": \\\"application/json\\\",\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows the information returned from the Get Transactions in a Batch API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"4a479bb5-d9e4-4d32-982b-f348c2f9a4b5\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"contactId\\\": \\\"CID_12345\\\",\\n                \\\"dateAddedToBatch\\\": \\\"2017-08-28 20:09:13\\\",\\n                \\\"transactionId\\\": \\\"CTR_23451\\\"\\n            },\\n            {\\n                \\\"contactId\\\": \\\"CID_12346\\\",\\n                \\\"dateAddedToBatch\\\": \\\"2017-08-28 20:09:13\\\",\\n                \\\"transactionId\\\": \\\"CTR_23452\\\"\\n            },\\n            {\\n                \\\"contactId\\\": \\\"CID_12347\\\",\\n                \\\"dateAddedToBatch\\\": \\\"2017-08-28 20:09:13\\\",\\n                \\\"transactionId\\\": \\\"CTR_23453\\\"\\n            }\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe following table provides details of the objects in the returned **elements** array:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**contactId**\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The ID of the contact that is associated with the specified transaction.\",\n    \"1-0\": \"**dateAddedToBatch**\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The date and time this transaction was added to the specified transaction batch. Specified in UTC as **yyyy-MM-dd HH:mm:ss**.\",\n    \"2-0\": \"**transactionId**\",\n    \"2-1\": \"String\",\n    \"2-2\": \"The ID of the transaction.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Get Transaction Batch\"\n}\n[/block]\nThe Get Transaction Batch API returns the creation date of the specified transaction batch. The following code example shows how to use the API.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Transaction Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ntransactionBatchId = \\\"BT_2345\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}\\\".format(dataCenter, directoryId, transactionBatchId)\\nheaders = {\\n    \\\"content-type\\\": \\\"application/json\\\",\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe response object returns the creation date of the specified transaction batch, as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"33ae1496-aeea-4315-9b3f-0564494d1cf3\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"batchId\\\": \\\"BT_2345\\\",\\n        \\\"creationDate\\\": \\\"2017-08-28 21:30:00\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**batchId**\",\n    \"0-1\": \"String\",\n    \"1-0\": \"**creationDate**\",\n    \"1-1\": \"String\",\n    \"0-2\": \"The transaction batch ID (as requested).\",\n    \"1-2\": \"The creation date and time of the specified transaction batch in the format **yyyy-MM-dd HH:mm:ss**.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Create Transaction Batch\"\n}\n[/block]\nThe Create Transaction Batch API lets you create a transaction batch. You supply an array of transaction IDs and the creation date for the batch. \n\nThe following code example shows how to create a transaction batch by providing an array of transaction IDs (**transactionIds**) and the transaction batch's creation date (**creationDate**).\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],\\n\\t\\\"creationDate\\\": \\\"2017-09-04 01:00:00\\\"\\n   }\\n\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows the returned transaction batch ID, which can be used with other APIs such as [Create Transaction Batch Survey Distribution](doc:create-transaction-batch-survey-distribution). \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"6372b60f-f28c-4072-8f00-878603f9e316\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"id\\\": \\\"BT_23456\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Update Transaction Batch\"\n}\n[/block]\nThe Update Transaction Batch API allows you to change the transactions and creation date associated with the specified transaction batch. The transactions replace the transactions in the transaction batch.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Update Transaction Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\ntransactionBatchId = \\\"BT_23456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}\\\".format(dataCenter, directoryId, transactionBatchId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n\\t\\\"transactionIds\\\": [\\n\\t\\t\\\"CTR_123456\\\",\\n\\t],\\n\\t\\\"creationDate\\\": \\\"2017-10-01 01:00:00\\\"\\n   }\\n\\nresponse = requests.put(baseUrl, json=data, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nA response object that shows the operation was successful is as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"864ba3e1-440d-47c1-901b-e4fc8c98d40b\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Delete Transaction Batch\"\n}\n[/block]\nTo delete a transaction batch you can use the Delete Transaction Batch API. The following code example shows how to delete a transaction batch with the batch ID of **BT_123456**.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Delete Transaction Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\ntransactionBatchId = \\\"BT_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}\\\".format(dataCenter, directoryId, transactionBatchId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\nresponse = requests.delete(baseUrl, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nA successful deletion returns a status code of 200 as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"c942cb5d-b8e8-4266-9095-6e899bd22970\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Add Transactions to a Batch\"\n}\n[/block]\nTo add transactions to an existing transaction batch, you can use the Add Transactions to a Batch API. The following code example attempts to add two transactions (**CTR_23456** and **CTR_23457**) to an existing transaction batch (**BT_1234**).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Add Transactions to a Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ntransactionBatchId = \\\"BT_1234\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}/transactions\\\".format(dataCenter, directoryId, transactionBatchId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n\\t\\\"transactionIds\\\": [\\n\\t\\t\\\"CTR_23456\\\",\\n    \\\"CTR_23457\\\",\\n\\t],\\n }\\n\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows the **result** object contains two objects, **added** and **failed**. The **added** object contains a collection of other objects that, in turn, contain the transactions that were added to the transaction batch successfully. The failed object contains the objects that could not be added to the transaction batch.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"b0e4e867-feb3-49b6-8d4c-479e5ba2e5e4\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"added\\\": {\\n            \\\"0\\\": {\\n                \\\"transactionId\\\": \\\"CTR_23456\\\"\\n            }\\n        },\\n        \\\"failed\\\": {\\n            \\\"1\\\": {\\n                \\\"error\\\": \\\"InvalidTransactionId\\\",\\n                \\\"errorMessage\\\": \\\"TransactionId: CTR_23457 not found in DB\\\"\\n            }\\n\\n        }\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**added**\",\n    \"0-1\": \"Object\",\n    \"1-0\": \"**failed**\",\n    \"1-1\": \"Object\",\n    \"0-2\": \"A collection of objects that contain the transaction IDs of successful additions to the specified transaction batch. Each successful transaction is identified by an index that starts at **0** and is incremented by one for each additional transaction.\",\n    \"1-2\": \"Objects that could not be added to the transaction batch. Each object contains **error** and **errorMessage** members. The **error** member is an error code that indicates the problem, and **errorMessage** is a description of the error.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Remove Transaction from a Batch\"\n}\n[/block]\nThe Remove Transaction from a Batch API removes one transaction from the specified transaction batch. The following code example shows how to remove the transaction **CTR_1235** from transaction batch **BT_2345**.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Remove Transaction from a Batch\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\ntransactionBatchId = \\\"BT_2345\\\"\\ntransactionId = \\\"CTR_1235\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}/transactions/{3}\\\".format(dataCenter, directoryId, transactionBatchId, transactionId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\nresponse = requests.delete(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nA successful deletion returns a 200 response code, as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"5fc3f157-ec09-4225-8f01-2463d1158fab\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"Discusses the transaction batch APIs in Target Audience","slug":"using-transaction-batches-in-target-audience","type":"basic","title":"Using Transaction Batches in Target Audience"}

Using Transaction Batches in Target Audience

Discusses the transaction batch APIs in Target Audience

*Transaction batches* group transactions for use with distributions; a *batch* or *transaction batch* is required to create a transaction batch survey distribution. The APIs discussed in this guide allow you to manage your transaction batches. [block:callout] { "type": "warning", "title": "Target Audience Only", "body": "These APIs are only available to Target Audience users." } [/block] The following APIs are discussed: - [Get Transaction Batches in Directory](#get-transaction-batches-in-directory) - [Get Transactions in a Batch](#get-transactions-in-a-batch) - [Get Transaction Batch](#get-transaction-batch) - [Create Transaction Batch](#create-transaction-batch) - [Update Transaction Batch](#update-transaction-batch) - [Delete Transaction Batch](#delete-transaction-batch) - [Add Transactions to a Batch](#add-transactions-to-a-batch) - [Remove Transaction from a Batch](#remove-transaction-from-a-batch) [block:api-header] { "title": "Get Transaction Batches in Directory" } [/block] The Get Transaction Batches in Directory API returns the batch ID and creation date for all of the transaction batches in the organization's Target Audience directory. [block:code] { "codes": [ { "code": "# Get Transaction Batches in a Directory\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches\".format(dataCenter, directoryId)\nheaders = {\n \"content-type\": \"application/json\",\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following response object shows the transaction batch information in the **elements** array. Each result contains the batch's ID and its creation date: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"ed9e81ee-6b2b-4ec2-9bef-4aac7cc1cd08\"\n },\n \"result\": {\n \"elements\": [\n {\n \"batchId\": \"BT_123456\",\n \"creationDate\": \"2017-10-02 20:15:00\"\n },\n {\n \"batchId\": \"BT_123457\",\n \"creationDate\": \"2017-10-02 21:30:00\"\n },\n {\n \"batchId\": \"BT_123458\",\n \"creationDate\": \"2017-10-02 21:30:00\"\n },\n {\n \"batchId\": \"BT_123459\",\n \"creationDate\": \"2017-10-03 01:00:00\"\n },\n {\n \"batchId\": \"BT_123470\",\n \"creationDate\": \"2017-10-04 01:00:00\"\n }\n ],\n \"nextPage\": null\n }\n}", "language": "json" } ] } [/block] The **elements** array contains descriptions of each transaction batch as shown below: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**batchId**", "0-1": "String", "1-0": "**creationDate**", "1-1": "String", "0-2": "The transaction batch ID.", "1-2": "The date and time the specified transaction batch was created in **yyyy-MM-dd HH:mm:ss** format." }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "title": "Get Transactions in a Batch" } [/block] The Get Transactions in a Batch API returns information for each transaction in a transaction batch. The information includes the contact ID associated with the transaction, the date the transaction was added to the transaction batch, and the transaction ID. [block:code] { "codes": [ { "code": "# Get Transactions in a Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\n\ndirectoryId = \"POOL_123456\"\ntransactionBatchId = \"BT_1234\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}/transactions\".format(dataCenter, directoryId, transactionBatchId)\nheaders = {\n \"content-type\": \"application/json\",\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following response object shows the information returned from the Get Transactions in a Batch API: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"4a479bb5-d9e4-4d32-982b-f348c2f9a4b5\"\n },\n \"result\": {\n \"elements\": [\n {\n \"contactId\": \"CID_12345\",\n \"dateAddedToBatch\": \"2017-08-28 20:09:13\",\n \"transactionId\": \"CTR_23451\"\n },\n {\n \"contactId\": \"CID_12346\",\n \"dateAddedToBatch\": \"2017-08-28 20:09:13\",\n \"transactionId\": \"CTR_23452\"\n },\n {\n \"contactId\": \"CID_12347\",\n \"dateAddedToBatch\": \"2017-08-28 20:09:13\",\n \"transactionId\": \"CTR_23453\"\n }\n ],\n \"nextPage\": null\n }\n}\n", "language": "json" } ] } [/block] The following table provides details of the objects in the returned **elements** array: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**contactId**", "0-1": "String", "0-2": "The ID of the contact that is associated with the specified transaction.", "1-0": "**dateAddedToBatch**", "1-1": "String", "1-2": "The date and time this transaction was added to the specified transaction batch. Specified in UTC as **yyyy-MM-dd HH:mm:ss**.", "2-0": "**transactionId**", "2-1": "String", "2-2": "The ID of the transaction." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "title": "Get Transaction Batch" } [/block] The Get Transaction Batch API returns the creation date of the specified transaction batch. The following code example shows how to use the API. [block:code] { "codes": [ { "code": "# Get Transaction Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_123456\"\ntransactionBatchId = \"BT_2345\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}\".format(dataCenter, directoryId, transactionBatchId)\nheaders = {\n \"content-type\": \"application/json\",\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] The response object returns the creation date of the specified transaction batch, as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"33ae1496-aeea-4315-9b3f-0564494d1cf3\"\n },\n \"result\": {\n \"batchId\": \"BT_2345\",\n \"creationDate\": \"2017-08-28 21:30:00\"\n }\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**batchId**", "0-1": "String", "1-0": "**creationDate**", "1-1": "String", "0-2": "The transaction batch ID (as requested).", "1-2": "The creation date and time of the specified transaction batch in the format **yyyy-MM-dd HH:mm:ss**." }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "title": "Create Transaction Batch" } [/block] The Create Transaction Batch API lets you create a transaction batch. You supply an array of transaction IDs and the creation date for the batch. The following code example shows how to create a transaction batch by providing an array of transaction IDs (**transactionIds**) and the transaction batch's creation date (**creationDate**). [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],\n\t\"creationDate\": \"2017-09-04 01:00:00\"\n }\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] The following response object shows the returned transaction batch ID, which can be used with other APIs such as [Create Transaction Batch Survey Distribution](doc:create-transaction-batch-survey-distribution). [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"6372b60f-f28c-4072-8f00-878603f9e316\"\n },\n \"result\": {\n \"id\": \"BT_23456\"\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Update Transaction Batch" } [/block] The Update Transaction Batch API allows you to change the transactions and creation date associated with the specified transaction batch. The transactions replace the transactions in the transaction batch. [block:code] { "codes": [ { "code": "# Update Transaction Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\ntransactionBatchId = \"BT_23456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}\".format(dataCenter, directoryId, transactionBatchId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n\t\"transactionIds\": [\n\t\t\"CTR_123456\",\n\t],\n\t\"creationDate\": \"2017-10-01 01:00:00\"\n }\n\nresponse = requests.put(baseUrl, json=data, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] A response object that shows the operation was successful is as follows: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"864ba3e1-440d-47c1-901b-e4fc8c98d40b\"\n }\n}", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "title": "Delete Transaction Batch" } [/block] To delete a transaction batch you can use the Delete Transaction Batch API. The following code example shows how to delete a transaction batch with the batch ID of **BT_123456**. [block:code] { "codes": [ { "code": "# Delete Transaction Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\ntransactionBatchId = \"BT_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}\".format(dataCenter, directoryId, transactionBatchId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] A successful deletion returns a status code of 200 as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"c942cb5d-b8e8-4266-9095-6e899bd22970\"\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Add Transactions to a Batch" } [/block] To add transactions to an existing transaction batch, you can use the Add Transactions to a Batch API. The following code example attempts to add two transactions (**CTR_23456** and **CTR_23457**) to an existing transaction batch (**BT_1234**). [block:code] { "codes": [ { "code": "# Add Transactions to a Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_123456\"\ntransactionBatchId = \"BT_1234\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}/transactions\".format(dataCenter, directoryId, transactionBatchId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n\t\"transactionIds\": [\n\t\t\"CTR_23456\",\n \"CTR_23457\",\n\t],\n }\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] The following response object shows the **result** object contains two objects, **added** and **failed**. The **added** object contains a collection of other objects that, in turn, contain the transactions that were added to the transaction batch successfully. The failed object contains the objects that could not be added to the transaction batch. [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"b0e4e867-feb3-49b6-8d4c-479e5ba2e5e4\"\n },\n \"result\": {\n \"added\": {\n \"0\": {\n \"transactionId\": \"CTR_23456\"\n }\n },\n \"failed\": {\n \"1\": {\n \"error\": \"InvalidTransactionId\",\n \"errorMessage\": \"TransactionId: CTR_23457 not found in DB\"\n }\n\n }\n }\n}", "language": "json" } ] } [/block] [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "**added**", "0-1": "Object", "1-0": "**failed**", "1-1": "Object", "0-2": "A collection of objects that contain the transaction IDs of successful additions to the specified transaction batch. Each successful transaction is identified by an index that starts at **0** and is incremented by one for each additional transaction.", "1-2": "Objects that could not be added to the transaction batch. Each object contains **error** and **errorMessage** members. The **error** member is an error code that indicates the problem, and **errorMessage** is a description of the error." }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "title": "Remove Transaction from a Batch" } [/block] The Remove Transaction from a Batch API removes one transaction from the specified transaction batch. The following code example shows how to remove the transaction **CTR_1235** from transaction batch **BT_2345**. [block:code] { "codes": [ { "code": "# Remove Transaction from a Batch\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\ntransactionBatchId = \"BT_2345\"\ntransactionId = \"CTR_1235\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactionbatches/{2}/transactions/{3}\".format(dataCenter, directoryId, transactionBatchId, transactionId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] A successful deletion returns a 200 response code, as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"5fc3f157-ec09-4225-8f01-2463d1158fab\"\n }\n}", "language": "json" } ] } [/block]