{"_id":"59f24a474aa81a003c3f7edd","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-10-26T20:49:11.195Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"This guide demonstrates the APIs that allow you to import contacts with transactions and obtain import status.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Target Audience\",\n  \"body\": \"These APIs can only be used with Target Audience.\"\n}\n[/block]\nThese samples use environment variables for configuration. See [Using the Code Samples with Your Installation](using-the-api-code-samples#using-the-code-samples-with-your-installation) for more infromation.\n\nThe following two APIs are discussed:\n\n- [Import Mailing List Contacts with Transactions](#import-mailing-list-contacts-with-transactions)\n- [Transaction Contacts Import Status](#transaction-contacts-import-status)\n[block:api-header]\n{\n  \"title\": \"Import Mailing List Contacts with Transactions\"\n}\n[/block]\nThe following code example shows how to import contact information with transactions. Before using this API, you need to create a transaction batch. See [Create Transaction Batch](doc:create-transaction-batch) for more information. Set the **batchId** property in the code example to the newly created transaction batch ID.\n\nThe **fields** array must contain all of the fields that appear in the **transactionData**. The **contacts** array contains contact objects. Its properties are covered in detail in [Create Contact In Mailing List](doc:create-contact-in-mailinglist).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Import Mailing List Contacts with Transactions\\n\\nimport os\\nimport requests\\n\\n# Setting user Parameters\\napiToken = os.environ[\\\"Q_API_TOKEN\\\"]\\ndataCenter = os.environ[\\\"Q_DATA_CENTER\\\"]\\ndirectoryId = os.environ[\\\"Q_TA_POOL_ID\\\"]\\n\\nmailingListId = \\\"CG_6VvXPvmYOwhj0vr\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/transactioncontacts\\\".format(dataCenter, directoryId, mailingListId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\n       \\\"transactionMeta\\\": {\\n         \\\"batchId\\\": \\\"BT_egQrgs9MYtG2mON\\\",\\n         \\\"fields\\\": [\\n           \\\"representative\\\",\\n           \\\"amount\\\",\\n           \\\"currency\\\"\\n         ]\\n       },\\n       \\\"contacts\\\": [\\n         {\\n           \\\"firstName\\\": \\\"John\\\",\\n           \\\"lastName\\\": \\\"Smith\\\",\\n           \\\"transactionData\\\": {\\n             \\\"representative\\\": 123456,\\n             \\\"amount\\\": \\\"1000.00\\\",\\n             \\\"currency\\\": \\\"Euro\\\"\\n           },\\n           \\\"unsubscribed\\\": True,\\n           \\\"embeddedData\\\": {\\n             \\\"city\\\": \\\"Paris\\\",\\n             \\\"country\\\": \\\"FR\\\"\\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 information on the status of the import, as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"202 - Accepted\\\",\\n        \\\"requestId\\\": \\\"6a1ad6af-aa3a-4fa6-81f7-6e42f9683cc9\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"contacts\\\": {\\n            \\\"unprocessed\\\": []\\n        },\\n        \\\"id\\\": \\\"PGRS_eP9Klpfqg6P3fJr\\\",\\n        \\\"status\\\": \\\"in progress\\\",\\n        \\\"tracking\\\": {\\n            \\\"url\\\": \\\"https://azuquatest.qualtrics.com/API/v3/directories/POOL_eDNcdUvmPoWYzPL/mailinglists/CG_6VvXPvmYOwhj0vr/transactioncontacts/PGRS_eP9Klpfqg6P3fJr\\\"\\n        }\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe following table provides details about the properties of the response object:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**contacts**\",\n    \"0-1\": \"Object\",\n    \"0-2\": \"Contains the **unprocessed** array containing transactions that were not processed.\",\n    \"1-0\": \"**id**\",\n    \"1-1\": \"String\",\n    \"2-0\": \"**status**\",\n    \"2-1\": \"String\",\n    \"3-0\": \"**tracking**\",\n    \"3-1\": \"Object\",\n    \"3-2\": \"Contains the **url** property that returns transaction contacts import status. This is the same endpoint used by the Transaction Contacts Import Status API.\",\n    \"1-2\": \"The transaction contacts import status id that identifies this import.\",\n    \"2-2\": \"Current status of the import.\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Transaction Contacts Import Status\"\n}\n[/block]\nThe Transaction Contacts Import Status API returns information about the current status of the contact transaction import that was started with the Import Mailing List Contacts with Transactions API. The following code example shows how to obtains the status of a contacts import.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Import Mailing List Contacts with Transactions\\n\\nimport os\\nimport requests\\n\\n# Setting user Parameters\\napiToken = os.environ[\\\"Q_API_TOKEN\\\"]\\ndataCenter = os.environ[\\\"Q_DATA_CENTER\\\"]\\ndirectoryId = os.environ[\\\"Q_TA_POOL_ID\\\"]\\n\\nmailingListId = \\\"CG_6VvXPvmYOwhj0vr\\\"\\nimportId = \\\"PGRS_51Fej4DxAXnrniB\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/transactioncontacts/{3}\\\".format(dataCenter, directoryId, mailingListId, importId)\\n\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe response object provides information about how many contacts and transactions were successfully imported and the import's progress.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"f8389ab7-7d8c-4084-83db-e9e505ea06ef\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"contacts\\\": {\\n            \\\"count\\\": {\\n                \\\"added\\\": 1,\\n                \\\"failed\\\": 0,\\n                \\\"updated\\\": 0\\n            }\\n        },\\n        \\\"percentComplete\\\": 100.0,\\n        \\\"status\\\": \\\"complete\\\",\\n        \\\"transactions\\\": {\\n            \\\"count\\\": {\\n                \\\"created\\\": 1\\n            }\\n        }\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe following table details the properties of the response object:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"**contacts**\",\n    \"0-1\": \"Object\",\n    \"1-0\": \"**percentComplete**\",\n    \"1-1\": \"Number\",\n    \"1-2\": \"Value from 0.0 to 100.0 that indicates how complete the contacts import is.\",\n    \"2-0\": \"**status**\",\n    \"2-1\": \"String\",\n    \"2-2\": \"When complete, this value changes to **complete**. Use the **status** instead of **percentComplete** to determine whether an import is done.\",\n    \"3-0\": \"**transactions**\",\n    \"3-1\": \"Object\",\n    \"3-2\": \"An object that contains the **count** object that contains the **created** number, which indicates how many new transactions were imported.\",\n    \"0-2\": \"Contains a **count** object that contains three properties. The **added** number indicates the number of new contacts that were created. The **failed** value indicates how many contains could not be imported, and **updated** counts the number of contacts that were updated (de-duplication matched a contact's email with an existing contact).\"\n  },\n  \"cols\": 3,\n  \"rows\": 4\n}\n[/block]","excerpt":"APIs to import mailing lists that include transactions","slug":"importing-mailing-lists-with-transactions","type":"basic","title":"Importing Mailing Lists with Transactions"}

Importing Mailing Lists with Transactions

APIs to import mailing lists that include transactions

This guide demonstrates the APIs that allow you to import contacts with transactions and obtain import status. [block:callout] { "type": "warning", "title": "Target Audience", "body": "These APIs can only be used with Target Audience." } [/block] These samples use environment variables for configuration. See [Using the Code Samples with Your Installation](using-the-api-code-samples#using-the-code-samples-with-your-installation) for more infromation. The following two APIs are discussed: - [Import Mailing List Contacts with Transactions](#import-mailing-list-contacts-with-transactions) - [Transaction Contacts Import Status](#transaction-contacts-import-status) [block:api-header] { "title": "Import Mailing List Contacts with Transactions" } [/block] The following code example shows how to import contact information with transactions. Before using this API, you need to create a transaction batch. See [Create Transaction Batch](doc:create-transaction-batch) for more information. Set the **batchId** property in the code example to the newly created transaction batch ID. The **fields** array must contain all of the fields that appear in the **transactionData**. The **contacts** array contains contact objects. Its properties are covered in detail in [Create Contact In Mailing List](doc:create-contact-in-mailinglist). [block:code] { "codes": [ { "code": "# Import Mailing List Contacts with Transactions\n\nimport os\nimport requests\n\n# Setting user Parameters\napiToken = os.environ[\"Q_API_TOKEN\"]\ndataCenter = os.environ[\"Q_DATA_CENTER\"]\ndirectoryId = os.environ[\"Q_TA_POOL_ID\"]\n\nmailingListId = \"CG_6VvXPvmYOwhj0vr\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/transactioncontacts\".format(dataCenter, directoryId, mailingListId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\n \"transactionMeta\": {\n \"batchId\": \"BT_egQrgs9MYtG2mON\",\n \"fields\": [\n \"representative\",\n \"amount\",\n \"currency\"\n ]\n },\n \"contacts\": [\n {\n \"firstName\": \"John\",\n \"lastName\": \"Smith\",\n \"transactionData\": {\n \"representative\": 123456,\n \"amount\": \"1000.00\",\n \"currency\": \"Euro\"\n },\n \"unsubscribed\": True,\n \"embeddedData\": {\n \"city\": \"Paris\",\n \"country\": \"FR\"\n }\n },\n ]\n }\n \nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The response object contains information on the status of the import, as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"202 - Accepted\",\n \"requestId\": \"6a1ad6af-aa3a-4fa6-81f7-6e42f9683cc9\"\n },\n \"result\": {\n \"contacts\": {\n \"unprocessed\": []\n },\n \"id\": \"PGRS_eP9Klpfqg6P3fJr\",\n \"status\": \"in progress\",\n \"tracking\": {\n \"url\": \"https://azuquatest.qualtrics.com/API/v3/directories/POOL_eDNcdUvmPoWYzPL/mailinglists/CG_6VvXPvmYOwhj0vr/transactioncontacts/PGRS_eP9Klpfqg6P3fJr\"\n }\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The following table provides details about the properties of the response object: [block:parameters] { "data": { "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-0": "**contacts**", "0-1": "Object", "0-2": "Contains the **unprocessed** array containing transactions that were not processed.", "1-0": "**id**", "1-1": "String", "2-0": "**status**", "2-1": "String", "3-0": "**tracking**", "3-1": "Object", "3-2": "Contains the **url** property that returns transaction contacts import status. This is the same endpoint used by the Transaction Contacts Import Status API.", "1-2": "The transaction contacts import status id that identifies this import.", "2-2": "Current status of the import." }, "cols": 3, "rows": 4 } [/block] [block:api-header] { "title": "Transaction Contacts Import Status" } [/block] The Transaction Contacts Import Status API returns information about the current status of the contact transaction import that was started with the Import Mailing List Contacts with Transactions API. The following code example shows how to obtains the status of a contacts import. [block:code] { "codes": [ { "code": "# Import Mailing List Contacts with Transactions\n\nimport os\nimport requests\n\n# Setting user Parameters\napiToken = os.environ[\"Q_API_TOKEN\"]\ndataCenter = os.environ[\"Q_DATA_CENTER\"]\ndirectoryId = os.environ[\"Q_TA_POOL_ID\"]\n\nmailingListId = \"CG_6VvXPvmYOwhj0vr\"\nimportId = \"PGRS_51Fej4DxAXnrniB\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/transactioncontacts/{3}\".format(dataCenter, directoryId, mailingListId, importId)\n\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] The response object provides information about how many contacts and transactions were successfully imported and the import's progress. [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"f8389ab7-7d8c-4084-83db-e9e505ea06ef\"\n },\n \"result\": {\n \"contacts\": {\n \"count\": {\n \"added\": 1,\n \"failed\": 0,\n \"updated\": 0\n }\n },\n \"percentComplete\": 100.0,\n \"status\": \"complete\",\n \"transactions\": {\n \"count\": {\n \"created\": 1\n }\n }\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] The following table details the properties of the response object: [block:parameters] { "data": { "h-0": "Property", "h-1": "Type", "h-2": "Description", "0-0": "**contacts**", "0-1": "Object", "1-0": "**percentComplete**", "1-1": "Number", "1-2": "Value from 0.0 to 100.0 that indicates how complete the contacts import is.", "2-0": "**status**", "2-1": "String", "2-2": "When complete, this value changes to **complete**. Use the **status** instead of **percentComplete** to determine whether an import is done.", "3-0": "**transactions**", "3-1": "Object", "3-2": "An object that contains the **count** object that contains the **created** number, which indicates how many new transactions were imported.", "0-2": "Contains a **count** object that contains three properties. The **added** number indicates the number of new contacts that were created. The **failed** value indicates how many contains could not be imported, and **updated** counts the number of contacts that were updated (de-duplication matched a contact's email with an existing contact)." }, "cols": 3, "rows": 4 } [/block]