{"_id":"58b9b9f74119312d00134ca1","category":{"_id":"59bc2c4e26ac9b0010a8b753","project":"55843604fd8d910d007b9502","version":"558444ceafccfd0d00fcb2bb","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-09-15T19:38:54.721Z","from_sync":false,"order":36,"slug":"target-audience-transaction-import","title":"Target Audience Transaction Import"},"__v":2,"parentDoc":null,"project":"55843604fd8d910d007b9502","user":"57ab6eabb5e8742000e17e7d","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":60,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-03-03T18:46:15.304Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"method":"post","results":{"codes":[{"status":202,"language":"json","code":"{\n  \"result\": {\n    \"id\": \"PGRS_2uhRr2nyY8O8NZZ\",\n    \"contacts\": {\n      \"unprocessed\": []\n    },\n    \"tracking\": {\n      \"url\": \"https://yourdatacenterid.qualtrics.com/API/v3/directories/POOL_XXXX6F11YY0Ci1x/mailinglists/CG_6LJM2t4OO045627/transactioncontacts/PGRS_2uhRr2nyY8O8NZZ\"\n    },\n    \"status\": \"in progress\"\n  },\n  \"meta\": {\n    \"httpStatus\":\"202 - Accepted\",\n    \"requestId\":\"01c8ffa2-af3c-42a5-9d3a-f6e93703b55f\"\n  }\n}","name":""}]},"settings":"","examples":{"codes":[{"code":"curl 'https://yourdatacenterid.qualtrics.com/API/v3/directories/POOL_XXXX6F11YY0Ci1x/mailinglists/CG_6LJM2t4OO045627/transactioncontacts' \\\n-X 'POST'  \\\n-H 'X-API-TOKEN: yourtokenhere' \\\n-H 'Content-Type: application/json' \\\n-d '\n     {\n       \"transactionMeta\": {\n         \"batchId\": \"BT_40VCYYyFVI5555F\",\n         \"fields\": [\n           \"tdfieldName1\",\n           \"tdfieldName2\"\n         ]\n       },\n       \"contacts\": [\n         {\n           \"firstName\": \"example_first\",\n           \"lastName\": \"example_last\",\n           \"transactionData\": {\n             \"tdfieldName1\": 121,\n             \"tdfieldName2\": \"td_value\"\n           },\n           \"unsubscribed\": true,\n           \"embeddedData\": {\n             \"edf1\": \"edv1\",\n             \"edf0\": \"edv0\"\n           }\n         },\n         {\n           ...\n         }\n       ]\n     }\n   '","language":"curl"}]},"auth":"required","params":[{"_id":"58b9c5283865630f00c2189c","ref":"","in":"path","required":true,"desc":"The directory ID, also known as the pool ID","default":"","type":"string","name":"directoryId"},{"_id":"58b9c5283865630f00c2189b","ref":"","in":"path","required":true,"desc":"The mailing list ID that the contacts should be imported into","default":"","type":"string","name":"mailingListId"},{"_id":"58b9c5283865630f00c21899","ref":"","in":"body","required":true,"desc":"A JSON object that specifies details regarding the per contact transactional data. Refer to the [documentation](doc:import-mailing-list-contacts-with-transactions#transactionmeta) below to see how this object is constructed.","default":"","type":"object","name":"transactionMeta"},{"_id":"58b9c5283865630f00c21898","ref":"","in":"body","required":true,"desc":"A JSON array of JSON objects, where each object represents information about a contact. Refer to the [documentation](doc:import-mailing-list-contacts-with-transactions#contacts) below to see how this object is constructed.","default":"","type":"array_object","name":"contacts"}],"url":"/v:version/directories/:directoryId/mailinglists/:mailingListId/transactioncontacts"},"isReference":false,"order":0,"body":"To check on the status of your import use [Transaction Contacts Import Status](doc:transaction-contacts-import-status) or follow the **url** value nested under the **tracking** key in the API response.\n[block:callout]\n{\n  \"type\": \"danger\",\n  \"title\": \"The size of the JSON body accepted by this API call is 5MB.\",\n  \"body\": \"The API request will return an error if the size of the body exceeds the aforementioned limit.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Understanding contacts.unprocessed in the API response\",\n  \"body\": \"This JSON array has items which are integers. Each integer represents the index of a JSON object in the API request's [contacts](doc:import-mailing-list-contacts-with-transactions#contacts) array.\\n\\nA [contact](doc:import-mailing-list-contacts-with-transactions#contact) can fail to process for several reasons, some of which are already detailed: [transactionData](doc:import-mailing-list-contacts-with-transactions#transactiondata), [embeddedData](doc:import-mailing-list-contacts-with-transactions#embeddeddata).\\n\\nSeveral other reasons include:\\n- **transactionData** or **embeddedData** are not JSON objects\\n- Keys in the **contact** object do not adhere to their type restrictions [specified](doc:import-mailing-list-contacts-with-transactions#contact)\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Contact deduplication\",\n  \"body\": \"If your organization has deduplication settings on, then any **contact** in the request body that matches an existing contact (in the directory or the specified mailing list) based on those deduplication settings will be merged with said existing contact.\\n\\nIf the previously existing contact has a transaction associated with it, and a **contact** matching by deduplication is included in this API request body, then the existing contact will be updated. Thus, the existing contact will now have two transactions instead of one. \\n\\nFurthermore, any information that was previously specified or not-specified for the contact, if included in this API's request body, will also be updated for the existing contact.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"transactionMeta\"\n}\n[/block]\nThe **transactionMeta** key accepts a JSON object, and is constructed as follows:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"JSON Syntax\",\n    \"0-0\": \"{\\n  \\\"fields\\\": [fields](doc:import-mailing-list-contacts-with-transactions#fields)\\n  \\\"batchId\\\": [batchId](doc:import-mailing-list-contacts-with-transactions#fields)\\n}\",\n    \"0-1\": \"\\\"transactionMeta\\\": {\\n  \\\"fields\\\": [\\n    \\\"field1\\\",\\n    \\\"field2\\\"\\n  ]\\n  \\\"batchId\\\": [batchId](doc:import-mailing-list-contacts-with-transactions#fields)\\n}\",\n    \"h-1\": \"As transactionMeta\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"fields\"\n}\n[/block]\n**JSON data type**: array\nMust have a minimum of one item in the array; there is no maximum.\n\nAll the items in this array must be JSON strings, or else the API request will return an error response.\n[block:api-header]\n{\n  \"title\": \"batchId\"\n}\n[/block]\n**JSON data type**: string\nThis key-value pair is required. The provided value must be a [Create Transaction Batch](doc:create-transaction-batch) ID.\n\nThe transaction batch associated with the provided ID must exist. If it does not exist, transactions will not be created and added.\n\nAll created transactions will be added to the specified transaction batch. You may paginate through all the [transactions in a batch](doc:get-transactions-in-a-batch). \n[block:api-header]\n{\n  \"title\": \"contacts\"\n}\n[/block]\n**JSON data type**: array\nMust have a minimum of one item in the array; there is no maximum.\n\nEach item in the **contacts** array for the API request must be a [contact](doc:import-mailing-list-contacts-with-transactions#contact).\n[block:api-header]\n{\n  \"title\": \"contact\"\n}\n[/block]\n**JSON data type**: object\n\nThe **required** keys are: \n- **transactionData**        ([notes](doc:import-mailing-list-contacts-with-transactions#transactiondata))\n\nThe **optional** keys are:\n- **firstName**        (value must be a JSON string)\n- **lastName**        (value must be a JSON string)\n- **email **       (value must be a JSON string and conform to valid email format)\n- **embeddedData**        ([notes](doc:import-mailing-list-contacts-with-transactions#embeddeddata))\n- **language**        (value must be a JSON string)\n- **extRef **       (value must be a JSON string)\n- **unsubscribed**        (value must be a JSON boolean)\n[block:api-header]\n{\n  \"title\": \"transactionData\"\n}\n[/block]\n**JSON data type**: object\n\nThis JSON object must, **at minimum**, have keys that match at least one of the elements seen in [fields](doc:import-mailing-list-contacts-with-transactions#fields). If this object has keys that are not specified in **transactionMeta.fields**, the extra keys are ignored. Transaction key-value pairs are solely dictated by the items in **transactionMeta.fields**.\n\nThe values of the keys can be JSON strings, numbers or booleans.\n[block:api-header]\n{\n  \"title\": \"embeddedData\"\n}\n[/block]\n**JSON data type**: object\n\nThis JSON object must have keys that **do not** match **any of** the elements seen in [fields](doc:import-mailing-list-contacts-with-transactions#fields). If this object has keys that are in **transactionMeta.fields**, the [contact](doc:import-mailing-list-contacts-with-transactions#contact) encapsulating this JSON object is added to **contacts.unprocessed** array in the API response.\n\nThe values of the keys can be JSON strings, numbers or booleans.","excerpt":"Import contacts into the specified mailing list - contacts must have associated transaction data","slug":"import-mailing-list-contacts-with-transactions","type":"endpoint","title":"Import Mailing List Contacts with Transactions"}

postImport Mailing List Contacts with Transactions

Import contacts into the specified mailing list - contacts must have associated transaction data

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

directoryId:
required
string
The directory ID, also known as the pool ID
mailingListId:
required
string
The mailing list ID that the contacts should be imported into

Body Params

transactionMeta:
required
object
A JSON object that specifies details regarding the per contact transactional data. Refer to the [documentation](doc:import-mailing-list-contacts-with-transactions#transactionmeta) below to see how this object is constructed.
contacts:
required
array of objects
A JSON array of JSON objects, where each object represents information about a contact. Refer to the [documentation](doc:import-mailing-list-contacts-with-transactions#contacts) below to see how this object is constructed.

Examples


Result Format


Documentation

To check on the status of your import use [Transaction Contacts Import Status](doc:transaction-contacts-import-status) or follow the **url** value nested under the **tracking** key in the API response. [block:callout] { "type": "danger", "title": "The size of the JSON body accepted by this API call is 5MB.", "body": "The API request will return an error if the size of the body exceeds the aforementioned limit." } [/block] [block:callout] { "type": "info", "title": "Understanding contacts.unprocessed in the API response", "body": "This JSON array has items which are integers. Each integer represents the index of a JSON object in the API request's [contacts](doc:import-mailing-list-contacts-with-transactions#contacts) array.\n\nA [contact](doc:import-mailing-list-contacts-with-transactions#contact) can fail to process for several reasons, some of which are already detailed: [transactionData](doc:import-mailing-list-contacts-with-transactions#transactiondata), [embeddedData](doc:import-mailing-list-contacts-with-transactions#embeddeddata).\n\nSeveral other reasons include:\n- **transactionData** or **embeddedData** are not JSON objects\n- Keys in the **contact** object do not adhere to their type restrictions [specified](doc:import-mailing-list-contacts-with-transactions#contact)" } [/block] [block:callout] { "type": "info", "title": "Contact deduplication", "body": "If your organization has deduplication settings on, then any **contact** in the request body that matches an existing contact (in the directory or the specified mailing list) based on those deduplication settings will be merged with said existing contact.\n\nIf the previously existing contact has a transaction associated with it, and a **contact** matching by deduplication is included in this API request body, then the existing contact will be updated. Thus, the existing contact will now have two transactions instead of one. \n\nFurthermore, any information that was previously specified or not-specified for the contact, if included in this API's request body, will also be updated for the existing contact." } [/block] [block:api-header] { "title": "transactionMeta" } [/block] The **transactionMeta** key accepts a JSON object, and is constructed as follows: [block:parameters] { "data": { "h-0": "JSON Syntax", "0-0": "{\n  \"fields\": [fields](doc:import-mailing-list-contacts-with-transactions#fields)\n  \"batchId\": [batchId](doc:import-mailing-list-contacts-with-transactions#fields)\n}", "0-1": "\"transactionMeta\": {\n  \"fields\": [\n    \"field1\",\n    \"field2\"\n  ]\n  \"batchId\": [batchId](doc:import-mailing-list-contacts-with-transactions#fields)\n}", "h-1": "As transactionMeta" }, "cols": 2, "rows": 1 } [/block] [block:api-header] { "title": "fields" } [/block] **JSON data type**: array Must have a minimum of one item in the array; there is no maximum. All the items in this array must be JSON strings, or else the API request will return an error response. [block:api-header] { "title": "batchId" } [/block] **JSON data type**: string This key-value pair is required. The provided value must be a [Create Transaction Batch](doc:create-transaction-batch) ID. The transaction batch associated with the provided ID must exist. If it does not exist, transactions will not be created and added. All created transactions will be added to the specified transaction batch. You may paginate through all the [transactions in a batch](doc:get-transactions-in-a-batch). [block:api-header] { "title": "contacts" } [/block] **JSON data type**: array Must have a minimum of one item in the array; there is no maximum. Each item in the **contacts** array for the API request must be a [contact](doc:import-mailing-list-contacts-with-transactions#contact). [block:api-header] { "title": "contact" } [/block] **JSON data type**: object The **required** keys are: - **transactionData**     ([notes](doc:import-mailing-list-contacts-with-transactions#transactiondata)) The **optional** keys are: - **firstName**     (value must be a JSON string) - **lastName**     (value must be a JSON string) - **email **     (value must be a JSON string and conform to valid email format) - **embeddedData**     ([notes](doc:import-mailing-list-contacts-with-transactions#embeddeddata)) - **language**     (value must be a JSON string) - **extRef **     (value must be a JSON string) - **unsubscribed**     (value must be a JSON boolean) [block:api-header] { "title": "transactionData" } [/block] **JSON data type**: object This JSON object must, **at minimum**, have keys that match at least one of the elements seen in [fields](doc:import-mailing-list-contacts-with-transactions#fields). If this object has keys that are not specified in **transactionMeta.fields**, the extra keys are ignored. Transaction key-value pairs are solely dictated by the items in **transactionMeta.fields**. The values of the keys can be JSON strings, numbers or booleans. [block:api-header] { "title": "embeddedData" } [/block] **JSON data type**: object This JSON object must have keys that **do not** match **any of** the elements seen in [fields](doc:import-mailing-list-contacts-with-transactions#fields). If this object has keys that are in **transactionMeta.fields**, the [contact](doc:import-mailing-list-contacts-with-transactions#contact) encapsulating this JSON object is added to **contacts.unprocessed** array in the API response. The values of the keys can be JSON strings, numbers or booleans.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}