{"_id":"59adc4b2046bbd003bc9d418","project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":59,"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"],"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:06.445Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"This guide discusses the APIs for working with contact transactions. Contact transactions allow you to save information about interactions with contacts (for example, purchase amounts, purchase locations, or whether the transaction occurred online). One use of transactions would be to present different survey questions depending on the data saved with the transaction.\n\nFor a tutorial on using contact transactions, see [Using Transactions in Target Audience](doc:using-transactions-in-target-audience).\n\nEach API requires your Target Audience Directory ID. See [Finding the Directory ID (or Pool ID) for Target Audience](https://api.qualtrics.com/docs/finding-qualtrics-ids#finding-the-directory-id-or-pool-id-for-target-aud) 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]\nThis guide covers the following APIs:\n\n- [Create Contact Transactions](#create-contact-transactions)\n- [Get Contact Transaction](#get-contact-transaction)\n- [List Contact Transactions](#list-contact-transactions)\n- [Append Contact Transaction](#append-contact-transaction)\n- [Update Contact Transaction](#update-contact-transaction)\n- [Delete Contract Transaction](#delete-contact-transaction)\n[block:api-header]\n{\n  \"title\": \"Create Contact Transactions\"\n}\n[/block]\nThe Create Contact Transactions API allows you to create transactions for one or more contacts. The API allows you to specify the contact, the contact's mailing list, the transaction date, and the key-value data associated with the transaction.\n\nThe following code example shows how to create three new transactions associated with one contact. The **a**, **b**, and **c** values are arbitrary values to identify the transaction status in the response object. You can use any value.\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        \\\"mailingListId\\\": \\\"CG_12345\\\",\\n        \\\"contactId\\\": \\\"CID_23456\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-27 18:00:00\\\",\\n        \\\"data\\\": {\\n\\t\\t        \\\"location\\\": \\\"Seattle\\\"\\n        }\\n      },\\n      \\\"b\\\": {\\n        \\\"mailingListId\\\": \\\"CG_12345\\\",\\n        \\\"contactId\\\": \\\"CID_23456\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-28 18:00:00\\\",\\n        \\\"data\\\": {\\n\\t\\t        \\\"location\\\": \\\"New York\\\"\\n        }\\n\\n      },\\n      \\\"c\\\": {\\n        \\\"mailingListId\\\": \\\"CG_12345\\\",\\n        \\\"contactId\\\": \\\"CID_23457\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-29 18:00:00\\\",\\n        \\\"data\\\": {\\n            \\\"location\\\": \\\"Chicago\\\"\\n        }\\n      }\\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 object contains two objects, `createdTransactions` for the transactions that were successfully created and `unprocessedTransactions` for the transactions that failed or are incomplete.\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\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe following table describes the objects in the response object:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`createdTransactions`\",\n    \"0-1\": \"Object\",\n    \"1-0\": \"`unprocessedTransactions`\",\n    \"1-1\": \"Object\",\n    \"0-2\": \"The transaction IDs for the transactions that were successfully created. These IDs can be used to create a transaction batch with [Create Transaction Batch](doc:create-transaction-batch).\",\n    \"1-2\": \"Transactions that have not completed processing.\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Get Contact Transaction\"\n}\n[/block]\nThe Get Contact Transaction API returns information about the specified transaction. The information includes:\n\n- The ID of the mailing list that is associated with the specified transaction.\n- The date and time the transaction occurred.\n- The transaction ID.\n- A `data` object that contains the transaction data.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Contact Transaction\\n\\nimport requests\\n\\n#Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ntransactionId = \\\"CTR_1234\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}\\\".format(dataCenter, directoryId, transactionId)\\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]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"ef461314-b5ac-4434-9a61-fbe24d45bd6b\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"contactId\\\": \\\"CID_6h4Y4JDg2zXYYzX\\\",\\n        \\\"data\\\": {\\n            \\\"currency\\\": \\\"Euro\\\",\\n            \\\"spend\\\": \\\"100\\\",\\n        },\\n        \\\"mailingListId\\\": \\\"CG_cZ5Xf3ANBJTEoRf\\\",\\n        \\\"transactionDate\\\": \\\"2017-08-18 20:51:00\\\",\\n        \\\"transactionId\\\": \\\"CTR_5b9PdrtcZ2ohrOl\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe following table describes the information returned:\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    \"1-0\": \"`data`\",\n    \"1-1\": \"Object\",\n    \"2-0\": \"`mailingListId`\",\n    \"2-1\": \"String\",\n    \"3-0\": \"`transactionDate`\",\n    \"3-1\": \"String\",\n    \"4-0\": \"`transactionId`\",\n    \"4-1\": \"String\",\n    \"0-2\": \"The contact ID that this transaction is associated with.\",\n    \"1-2\": \"The transaction data object. It consists of string values representing a user-defined transaction.\",\n    \"2-2\": \"The mailing list associated with the specified transaction.\",\n    \"3-2\": \"The date and time of the specified transaction.\",\n    \"4-2\": \"The transaction ID.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"List Contact Transactions\"\n}\n[/block]\nThe List Contact Transactions API returns information about all of the transactions associated with a contact. The information returned includes the contact ID and mailing list ID that are associated with the transaction, the transaction date and time, and the transaction ID.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Transaction Data\",\n  \"body\": \"This API does not return the transactions' `data` objects. You need to call Get Contact Transaction for each transaction you would like the transaction `data` object.\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# List Contact Transactions\\n\\nimport requests\\n\\n#Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\ncontactId = \\\"CID_1234\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}/transactions\\\".format(dataCenter, directoryId, contactId)\\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]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"e05c4184-25b8-41ec-ab16-e8fc873e9973\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"contactId\\\": \\\"CID_12345\\\",\\n                \\\"mailingListId\\\": \\\"CG_23456\\\",\\n                \\\"transactionDate\\\": \\\"2017-08-17 18:00:00\\\",\\n                \\\"transactionId\\\": \\\"CTR_12345\\\"\\n            },\\n            {\\n                \\\"contactId\\\": \\\"CID_12345\\\",\\n                \\\"mailingListId\\\": \\\"CG_23457\\\",\\n                \\\"transactionDate\\\": \\\"2017-08-15 18:00:00\\\",\\n                \\\"transactionId\\\": \\\"CTR_12347\\\"\\n            }\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe returned `elements` array contains information on every transaction associated with the specified contact. Each object in the `elements` array contains the following members:\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    \"1-0\": \"`mailingListId`\",\n    \"1-1\": \"String\",\n    \"2-0\": \"`transactionDate`\",\n    \"2-1\": \"String\",\n    \"3-0\": \"`transactionId`\",\n    \"3-1\": \"String\",\n    \"0-2\": \"The contact ID that the transaction is associated with.\",\n    \"1-2\": \"The mailing list ID that the transaction is associated with.\",\n    \"2-2\": \"The transaction date as **yyyy-MM-dd HH:mm:ss**.\",\n    \"3-2\": \"The transaction's ID.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Append Contact Transaction\"\n}\n[/block]\nThe Append Contract Transaction allows you to modify transaction data. Its behavior is slightly different from Update Contact Transaction because it does not allow the transaction date and time to be modified.\n\nThe following code example shows how to change values in an existing transaction:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Append Contact Transaction\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ntransactionId = \\\"CTR_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}\\\".format(dataCenter, directoryId, transactionId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n        \\\"data\\\": {\\n          \\\"type\\\": \\\"NotAStoreVisit\\\",\\n          \\\"spend\\\": \\\"10.0\\\",\\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 object indicates whether the operation completed successfully, as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"d6842628-c198-4c14-892c-16c684808613\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe following table shows the results of using the Append Contact Transaction API. The first column shows the operation, such as setting a value to an empty string (\"\"). The second column shows what happens if that operation is applied to values that already exist in the transaction. The third column shows what happens if there is no value of that name already in the transaction.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Set the Value to\",\n    \"h-1\": \"If the Value Already Exists\",\n    \"h-2\": \"If the Value Does Not Exist\",\n    \"0-0\": \"Empty string\",\n    \"1-0\": \"**null**\",\n    \"2-0\": \"Non-empty string.\",\n    \"0-1\": \"The value is deleted from transaction.\",\n    \"1-1\": \"The change is ignored. The value retains its original value.\",\n    \"2-1\": \"The value is changed to the new string.\",\n    \"0-2\": \"The value is not added to the transaction.\",\n    \"1-2\": \"The value is not added to the transaction.\",\n    \"2-2\": \"A new value is created and added to transaction.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nFor example, you currently have a transaction with the following data:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"\\\"data\\\": {\\n  \\\"currency\\\": \\\"Euro\\\",\\n  \\\"spend\\\": \\\"100\\\",\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Transaction data (JSON)\"\n    }\n  ]\n}\n[/block]\nYou invoke Append Contact Transaction with the following data (using **None** for **null** in Python):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"currency\\\": \\\"\\\",\\n  \\\"spend\\\": None,\\n  \\\"newValue\\\": \\\"new\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Modification (Python)\"\n    }\n  ]\n}\n[/block]\nThe resulting transaction will contain the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"spend\\\": \\\"100\\\",\\n  \\\"newValue\\\": \\\"new\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe `currency` value will be removed, the **None** (**null**) value will be ignored, and `newValue` will be set to **new**.\n[block:api-header]\n{\n  \"title\": \"Update Contact Transaction\"\n}\n[/block]\nThe Update Contact Transaction API allows you to update transaction data and the transaction date and time. The API operates slightly differently than the Append Contact Transaction API.\n\nThe following code sample shows how to update an existing transaction's values and its date and time.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Update Contact Transaction\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATA CENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345\\\"\\ntransactionId = \\\"CTR_23456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}\\\".format(dataCenter, directoryId, transactionId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n        \\\"data\\\": {\\n          \\\"currency\\\": \\\"Euro\\\",\\n          \\\"spend\\\": \\\"100.00\\\",\\n        },\\n\\t\\t\\\"transactionDate\\\": \\\"2017-08-18 20:51:00\\\"\\n   }\\n\\nresponse = requests.put(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe following response object shows successful completion of the operation:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"68d7a8c3-f098-42d9-b384-35fa65ff2382\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe following table shows how different values affect a transaction. For more information about how to interpret the information in the following table, see [Append Contact Transaction](#append-contact-transaction) above.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"Empty string\",\n    \"1-0\": \"**null**\",\n    \"2-0\": \"Non-empty string\",\n    \"h-0\": \"Set Value To\",\n    \"h-1\": \"If the Value Already Exists\",\n    \"h-2\": \"If the Value Does Not Exist\",\n    \"0-1\": \"The value is changed to empty string.\",\n    \"0-2\": \"A new value created, added to the transaction, and set to an empty string.\",\n    \"1-1\": \"The value is deleted from the transaction.\",\n    \"1-2\": \"The value is not added to the transaction.\",\n    \"2-1\": \"The value is changed to the new string.\",\n    \"2-2\": \"A new value is created and added to the transaction.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Delete Contact Transaction\"\n}\n[/block]\nThe Delete Contact Transaction API deletes an entire contact transaction. The following code example shows how the API can be used to delete one transaction.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Delete Contact Transaction\\n\\nimport requests\\n\\n#Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = 'YOUR DATA CENTER'\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ntransactionId  = \\\"CTR_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}/\\\".format(dataCenter, directoryId, transactionId)\\nheaders = {\\n    \\\"content-type\\\": \\\"application/json\\\",\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.delete(baseUrl, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows the successful completion of the Delete Contact Transaction API.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"d0a303d0-1f29-4e80-9342-f9d13cd1d0c9\\\"\\n    }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]","excerpt":"Discusses the contact transaction APIs in Target Audience","slug":"using-contact-transactions-in-target-audience","type":"basic","title":"Using Contact Transactions in Target Audience"}

Using Contact Transactions in Target Audience

Discusses the contact transaction APIs in Target Audience

This guide discusses the APIs for working with contact transactions. Contact transactions allow you to save information about interactions with contacts (for example, purchase amounts, purchase locations, or whether the transaction occurred online). One use of transactions would be to present different survey questions depending on the data saved with the transaction. For a tutorial on using contact transactions, see [Using Transactions in Target Audience](doc:using-transactions-in-target-audience). Each API requires your Target Audience Directory ID. See [Finding the Directory ID (or Pool ID) for Target Audience](https://api.qualtrics.com/docs/finding-qualtrics-ids#finding-the-directory-id-or-pool-id-for-target-aud) for more information. [block:callout] { "type": "warning", "title": "Target Audience Only", "body": "These APIs are only available to Target Audience users." } [/block] This guide covers the following APIs: - [Create Contact Transactions](#create-contact-transactions) - [Get Contact Transaction](#get-contact-transaction) - [List Contact Transactions](#list-contact-transactions) - [Append Contact Transaction](#append-contact-transaction) - [Update Contact Transaction](#update-contact-transaction) - [Delete Contract Transaction](#delete-contact-transaction) [block:api-header] { "title": "Create Contact Transactions" } [/block] The Create Contact Transactions API allows you to create transactions for one or more contacts. The API allows you to specify the contact, the contact's mailing list, the transaction date, and the key-value data associated with the transaction. The following code example shows how to create three new transactions associated with one contact. The **a**, **b**, and **c** values are arbitrary values to identify the transaction status in the response object. You can use any value. [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 \"mailingListId\": \"CG_12345\",\n \"contactId\": \"CID_23456\",\n \"transactionDate\": \"2017-08-27 18:00:00\",\n \"data\": {\n\t\t \"location\": \"Seattle\"\n }\n },\n \"b\": {\n \"mailingListId\": \"CG_12345\",\n \"contactId\": \"CID_23456\",\n \"transactionDate\": \"2017-08-28 18:00:00\",\n \"data\": {\n\t\t \"location\": \"New York\"\n }\n\n },\n \"c\": {\n \"mailingListId\": \"CG_12345\",\n \"contactId\": \"CID_23457\",\n \"transactionDate\": \"2017-08-29 18:00:00\",\n \"data\": {\n \"location\": \"Chicago\"\n }\n }\n\n\n }\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The response object contains two objects, `createdTransactions` for the transactions that were successfully created and `unprocessedTransactions` for the transactions that failed or are incomplete. [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}\n", "language": "json", "name": "Response" } ] } [/block] The following table describes the objects in the response object: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`createdTransactions`", "0-1": "Object", "1-0": "`unprocessedTransactions`", "1-1": "Object", "0-2": "The transaction IDs for the transactions that were successfully created. These IDs can be used to create a transaction batch with [Create Transaction Batch](doc:create-transaction-batch).", "1-2": "Transactions that have not completed processing." }, "cols": 3, "rows": 2 } [/block] [block:api-header] { "title": "Get Contact Transaction" } [/block] The Get Contact Transaction API returns information about the specified transaction. The information includes: - The ID of the mailing list that is associated with the specified transaction. - The date and time the transaction occurred. - The transaction ID. - A `data` object that contains the transaction data. [block:code] { "codes": [ { "code": "# Get Contact Transaction\n\nimport requests\n\n#Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_123456\"\ntransactionId = \"CTR_1234\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}\".format(dataCenter, directoryId, transactionId)\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] [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"ef461314-b5ac-4434-9a61-fbe24d45bd6b\"\n },\n \"result\": {\n \"contactId\": \"CID_6h4Y4JDg2zXYYzX\",\n \"data\": {\n \"currency\": \"Euro\",\n \"spend\": \"100\",\n },\n \"mailingListId\": \"CG_cZ5Xf3ANBJTEoRf\",\n \"transactionDate\": \"2017-08-18 20:51:00\",\n \"transactionId\": \"CTR_5b9PdrtcZ2ohrOl\"\n }\n}", "language": "json" } ] } [/block] The following table describes the information returned: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`contactId`", "0-1": "String", "1-0": "`data`", "1-1": "Object", "2-0": "`mailingListId`", "2-1": "String", "3-0": "`transactionDate`", "3-1": "String", "4-0": "`transactionId`", "4-1": "String", "0-2": "The contact ID that this transaction is associated with.", "1-2": "The transaction data object. It consists of string values representing a user-defined transaction.", "2-2": "The mailing list associated with the specified transaction.", "3-2": "The date and time of the specified transaction.", "4-2": "The transaction ID." }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "title": "List Contact Transactions" } [/block] The List Contact Transactions API returns information about all of the transactions associated with a contact. The information returned includes the contact ID and mailing list ID that are associated with the transaction, the transaction date and time, and the transaction ID. [block:callout] { "type": "info", "title": "Transaction Data", "body": "This API does not return the transactions' `data` objects. You need to call Get Contact Transaction for each transaction you would like the transaction `data` object." } [/block] [block:code] { "codes": [ { "code": "# List Contact Transactions\n\nimport requests\n\n#Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\ncontactId = \"CID_1234\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}/transactions\".format(dataCenter, directoryId, contactId)\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] [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"e05c4184-25b8-41ec-ab16-e8fc873e9973\"\n },\n \"result\": {\n \"elements\": [\n {\n \"contactId\": \"CID_12345\",\n \"mailingListId\": \"CG_23456\",\n \"transactionDate\": \"2017-08-17 18:00:00\",\n \"transactionId\": \"CTR_12345\"\n },\n {\n \"contactId\": \"CID_12345\",\n \"mailingListId\": \"CG_23457\",\n \"transactionDate\": \"2017-08-15 18:00:00\",\n \"transactionId\": \"CTR_12347\"\n }\n ],\n \"nextPage\": null\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The returned `elements` array contains information on every transaction associated with the specified contact. Each object in the `elements` array contains the following members: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`contactId`", "0-1": "String", "1-0": "`mailingListId`", "1-1": "String", "2-0": "`transactionDate`", "2-1": "String", "3-0": "`transactionId`", "3-1": "String", "0-2": "The contact ID that the transaction is associated with.", "1-2": "The mailing list ID that the transaction is associated with.", "2-2": "The transaction date as **yyyy-MM-dd HH:mm:ss**.", "3-2": "The transaction's ID." }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "title": "Append Contact Transaction" } [/block] The Append Contract Transaction allows you to modify transaction data. Its behavior is slightly different from Update Contact Transaction because it does not allow the transaction date and time to be modified. The following code example shows how to change values in an existing transaction: [block:code] { "codes": [ { "code": "# Append Contact Transaction\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_123456\"\ntransactionId = \"CTR_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}\".format(dataCenter, directoryId, transactionId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n \"data\": {\n \"type\": \"NotAStoreVisit\",\n \"spend\": \"10.0\",\n },\n }\n\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The response object indicates whether the operation completed successfully, as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"d6842628-c198-4c14-892c-16c684808613\"\n }\n}", "language": "json", "name": "Response" } ] } [/block] The following table shows the results of using the Append Contact Transaction API. The first column shows the operation, such as setting a value to an empty string (""). The second column shows what happens if that operation is applied to values that already exist in the transaction. The third column shows what happens if there is no value of that name already in the transaction. [block:parameters] { "data": { "h-0": "Set the Value to", "h-1": "If the Value Already Exists", "h-2": "If the Value Does Not Exist", "0-0": "Empty string", "1-0": "**null**", "2-0": "Non-empty string.", "0-1": "The value is deleted from transaction.", "1-1": "The change is ignored. The value retains its original value.", "2-1": "The value is changed to the new string.", "0-2": "The value is not added to the transaction.", "1-2": "The value is not added to the transaction.", "2-2": "A new value is created and added to transaction." }, "cols": 3, "rows": 3 } [/block] For example, you currently have a transaction with the following data: [block:code] { "codes": [ { "code": "\"data\": {\n \"currency\": \"Euro\",\n \"spend\": \"100\",\n}", "language": "json", "name": "Transaction data (JSON)" } ] } [/block] You invoke Append Contact Transaction with the following data (using **None** for **null** in Python): [block:code] { "codes": [ { "code": "{\n \"currency\": \"\",\n \"spend\": None,\n \"newValue\": \"new\"\n}", "language": "json", "name": "Modification (Python)" } ] } [/block] The resulting transaction will contain the following: [block:code] { "codes": [ { "code": "{\n \"spend\": \"100\",\n \"newValue\": \"new\"\n}", "language": "json" } ] } [/block] The `currency` value will be removed, the **None** (**null**) value will be ignored, and `newValue` will be set to **new**. [block:api-header] { "title": "Update Contact Transaction" } [/block] The Update Contact Transaction API allows you to update transaction data and the transaction date and time. The API operates slightly differently than the Append Contact Transaction API. The following code sample shows how to update an existing transaction's values and its date and time. [block:code] { "codes": [ { "code": "# Update Contact Transaction\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATA CENTER\"\n\ndirectoryId = \"POOL_12345\"\ntransactionId = \"CTR_23456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}\".format(dataCenter, directoryId, transactionId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n \"data\": {\n \"currency\": \"Euro\",\n \"spend\": \"100.00\",\n },\n\t\t\"transactionDate\": \"2017-08-18 20:51:00\"\n }\n\nresponse = requests.put(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "json" } ] } [/block] The following response object shows successful completion of the operation: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"68d7a8c3-f098-42d9-b384-35fa65ff2382\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The following table shows how different values affect a transaction. For more information about how to interpret the information in the following table, see [Append Contact Transaction](#append-contact-transaction) above. [block:parameters] { "data": { "0-0": "Empty string", "1-0": "**null**", "2-0": "Non-empty string", "h-0": "Set Value To", "h-1": "If the Value Already Exists", "h-2": "If the Value Does Not Exist", "0-1": "The value is changed to empty string.", "0-2": "A new value created, added to the transaction, and set to an empty string.", "1-1": "The value is deleted from the transaction.", "1-2": "The value is not added to the transaction.", "2-1": "The value is changed to the new string.", "2-2": "A new value is created and added to the transaction." }, "cols": 3, "rows": 3 } [/block] [block:api-header] { "title": "Delete Contact Transaction" } [/block] The Delete Contact Transaction API deletes an entire contact transaction. The following code example shows how the API can be used to delete one transaction. [block:code] { "codes": [ { "code": "# Delete Contact Transaction\n\nimport requests\n\n#Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = 'YOUR DATA CENTER'\n\ndirectoryId = \"POOL_123456\"\ntransactionId = \"CTR_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/transactions/{2}/\".format(dataCenter, directoryId, transactionId)\nheaders = {\n \"content-type\": \"application/json\",\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] The following response object shows the successful completion of the Delete Contact Transaction API. [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"d0a303d0-1f29-4e80-9342-f9d13cd1d0c9\"\n }\n}", "language": "json", "name": "Response" } ] } [/block]