{"_id":"596fb5f0ccf6fe00305ccd91","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":"59b054613c3e1b0019cf27d9","project":"55843604fd8d910d007b9502","version":"558444ceafccfd0d00fcb2bb","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-09-06T20:02:41.600Z","from_sync":false,"order":2,"slug":"using-target-audience","title":"Using Target Audience"},"user":"5919f13aff66b00f00f1948c","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-07-19T19:41:36.422Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"This guide contains information about using the APIs for managing contacts in mailing lists for Target Audience. For information on managing mailing lists themselves, see [Managing Mailing Lists for Target Audience](doc:managing-mailing-lists-for-target-audience).\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Target Audience Only\",\n  \"body\": \"These APIs are only available to Target Audience users.\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"These APIs do not support actions on shared (global) mailing lists. You need to use the V2 APIs to work with global mailing lists.\",\n  \"title\": \"Shared Mailing Lists Unsupported\"\n}\n[/block]\nThis guide covers the following APIs:\n\n- [Create Contact in Mailing List](#create-contact-in-mailing-list)\n- [List Contacts in Mailing List](#list-contacts-in-mailing-list)\n- [Get Contact in Mailing List](#get-contact-in-mailing-list)\n- [Update Contact in Mailing List](#update-contact-in-mailing-list)\n- [Delete Contact in Mailing List](#delete-contact-in-mailing-list)\n[block:api-header]\n{\n  \"title\": \"Create Contact in Mailing List\"\n}\n[/block]\nThis API allows you to create a new contact in the specified mailing list. This API is the only way to add a contact to a mailing list; you cannot copy a contact from the organization's contacts directory to a mailing list. \n\nWhen you use this API, the contact you create is also created in the organization's contacts directory.  This means that if the contact already exists in the organization's contacts directory, a duplicate will be created. You can then use Target Audience's deduplication tool to remove these duplicate contacts. See [Manage Directory Duplicates](https://www.qualtrics.com/support/target-audience/directory/manage-duplicates-2/) for more information.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create Contact in Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_1234567\\\"\\nmailingListId = \\\"CG_34567890\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts\\\".format(dataCenter, directoryId, mailingListId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\\"firstName\\\": \\\"James\\\",\\n\\t\\\"lastName\\\": \\\"Smith\\\",\\n\\t\\\"email\\\": \\\"js:::at:::example.com\\\",\\n\\t\\\"phone\\\": \\\"8005552000\\\",\\n\\t\\\"embeddedData\\\": { \\\"level\\\": \\\"mid\\\", \\\"area\\\": \\\"coast\\\" },\\n\\t\\\"language\\\": \\\"en\\\",\\n\\t\\\"extRef\\\": \\\"1234567\\\",\\n\\t\\\"unsubscribed\\\": True,\\n\\t }\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows a typical result from this API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"641ca8da-fb07-4319-907b-ab45af1a93c2\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"id\\\": \\\"CID_123456\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"List Contacts in Mailing List\"\n}\n[/block]\nThe List Contacts API returns all of the contacts on the specified mailing list. The information on each contact includes:\n\n- The contact's ID\n- The email address\n- The external reference (user-defined data attached to a contact)\n- The contact's first name\n- The contact's last name\n- The language (if specified)\n- The phone number\n- Whether the contact has unsubscribed (\"opted-out\") of the specified mailing list\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# List Contacts in Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\n\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\nmailingListId = \\\"CG_123456\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts\\\".format(dataCenter, directoryId, mailingListId)\\nheaders = {\\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 shows an example response returned from this API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"7de14d38-f5ed-49d0-9ff0-773e12b896b8\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"contactId\\\": \\\"CID_123456\\\",\\n                \\\"email\\\": \\\"js@example.com\\\",\\n                \\\"extRef\\\": \\\"1234567\\\",\\n                \\\"firstName\\\": \\\"James\\\",\\n                \\\"language\\\": \\\"en\\\",\\n                \\\"lastName\\\": \\\"Smith\\\",\\n                \\\"phone\\\": \\\"8005552000\\\",\\n                \\\"unsubscribed\\\": false\\n            },\\n            {\\n                \\\"contactId\\\": \\\"CID_3456789\\\",\\n                \\\"email\\\": \\\"person@example.com\\\",\\n                \\\"extRef\\\": \\\"12345678\\\",\\n                \\\"firstName\\\": \\\"John\\\",\\n                \\\"language\\\": \\\"en\\\",\\n                \\\"lastName\\\": \\\"Smith\\\",\\n                \\\"phone\\\": \\\"8005551212\\\",\\n                \\\"unsubscribed\\\": true\\n            }\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Get Contact in Mailing List\"\n}\n[/block]\nThe Get Contact in Mailing List API returns information about the specified contact in the specified mailing list. The information is almost identical to the information returned by the [Get Contact API](https://api.qualtrics.com/docs/managing-directory-contacts-for-target-audience#get-contact), with two differences:\n\n1. This API does not return mailing list membership information.\n2. This API returns an ID that uniquely identifies the contact in this mailing list (`contactLookupId`).\n\nThe following sample shows how to use the Get Contact in Mailing List API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Contact in Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_1234567\\\"\\nmailingListId = \\\"CG_12345\\\"\\ncontactId = \\\"CID_1234567\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}\\\".format(dataCenter, directoryId, mailingListId, contactId)\\nheaders = {\\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 following shows an example of the response that this endpoint returns:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"7684ed69-832d-4f91-899d-d6c8aa7ccea2\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"contactId\\\": \\\"CID_1234567\\\",\\n        \\\"contactLookupId\\\": \\\"CGC_12345\\\",\\n        \\\"creationDate\\\": 1500667426000,\\n        \\\"directoryUnsubscribeDate\\\": null,\\n        \\\"directoryUnsubscribed\\\": false,\\n        \\\"email\\\": \\\"js@example.com\\\",\\n        \\\"emailDomain\\\": null,\\n        \\\"embeddedData\\\": {\\n            \\\"area\\\": \\\"coast\\\",\\n            \\\"level\\\": \\\"mid\\\"\\n        },\\n        \\\"extRef\\\": \\\"1234567\\\",\\n        \\\"firstName\\\": \\\"James\\\",\\n        \\\"language\\\": \\\"en\\\",\\n        \\\"lastModified\\\": 1500667426000,\\n        \\\"lastName\\\": \\\"Smith\\\",\\n        \\\"mailingListUnsubscribeDate\\\": null,\\n        \\\"mailingListUnsubscribed\\\": false,\\n        \\\"phone\\\": \\\"8005552000\\\",\\n        \\\"stats\\\": {\\n            \\\"AvgTimeToRespond\\\": \\\"0.0\\\",\\n            \\\"DataIntegrity\\\": \\\"100\\\",\\n            \\\"EmailCount\\\": \\\"1\\\",\\n            \\\"InviteCount\\\": \\\"1\\\",\\n            \\\"LastEmailDate\\\": \\\"2017-07-25 21:00:31\\\",\\n            \\\"LastInviteDate\\\": \\\"2017-07-25 21:00:31\\\",\\n            \\\"LastResponseDate\\\": \\\"2017-07-25 21:02:19\\\",\\n            \\\"MonthEmailCount\\\": \\\"1\\\",\\n            \\\"MonthInviteCount\\\": \\\"1\\\",\\n            \\\"Points\\\": \\\"0\\\",\\n            \\\"ResponseCount\\\": \\\"1\\\",\\n            \\\"ResponseRate\\\": \\\"1.0\\\"\\n        },\\n        \\\"writeBlanks\\\": false\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe result contains the following data:\n\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 contact ID.\",\n    \"1-0\": \"`contactLookupId`\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The contact lookup ID\",\n    \"2-0\": \"`creationDate`\",\n    \"2-1\": \"Number\",\n    \"2-2\": \"Date and time this contact's record was created. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"3-0\": \"`directoryUnsubscribeDate`\",\n    \"3-1\": \"Number\",\n    \"4-0\": \"`directoryUnsubscribed`\",\n    \"4-1\": \"Boolean\",\n    \"5-0\": \"`email`\",\n    \"5-1\": \"String\",\n    \"6-0\": \"`emailDomain`\",\n    \"6-1\": \"String\",\n    \"7-0\": \"`embeddedData`\",\n    \"7-1\": \"Object\",\n    \"8-0\": \"`extRef`\",\n    \"8-1\": \"String\",\n    \"9-0\": \"`firstName`\",\n    \"9-1\": \"String\",\n    \"10-0\": \"`language`\",\n    \"10-1\": \"String\",\n    \"11-0\": \"`lastModified`\",\n    \"11-1\": \"Number\",\n    \"12-0\": \"`lastName`\",\n    \"12-1\": \"String\",\n    \"13-0\": \"`mailingListUnsubscribeDate`\",\n    \"14-0\": \"`mailingListUnsubscribed`\",\n    \"15-0\": \"`phone`\",\n    \"15-1\": \"String\",\n    \"16-0\": \"`stats`\",\n    \"16-1\": \"Object\",\n    \"17-0\": \"`writeBlanks`\",\n    \"17-1\": \"Boolean\",\n    \"7-2\": \"The embedded data object contains extra metadata that you want to associate with contacts. This user-defined data could include such data as birthplace, gender, employment status, etc. See [Update Contact](doc:managing-directory-contacts#update-contact) below for an example of setting the embedded data object.\",\n    \"8-2\": \"External reference. You can place any string data here that you need to attach to a contact.\",\n    \"3-2\": \"Date and time the user opted out of the directory. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"4-2\": \"Indicates whether the user opted out of the directory.\",\n    \"5-2\": \"The contact's email address.\",\n    \"6-2\": \"The contact's email domain.\",\n    \"9-2\": \"The contact's first name or given name.\",\n    \"10-2\": \"The contact's language if set.\",\n    \"11-2\": \"Date and time this record was last modified. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"12-2\": \"The contact's last name or surname.\",\n    \"13-2\": \"Date and time the user opted out of this mailing list. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"16-2\": \"The stats object for the contact. See the next section for information about this object.\",\n    \"17-2\": \"Whether to write blanks.\",\n    \"15-2\": \"The contact's phone number.\",\n    \"13-1\": \"Number\",\n    \"14-1\": \"Boolean\",\n    \"14-2\": \"Whether the user has opted out of receiving email through this mailing list.\"\n  },\n  \"cols\": 3,\n  \"rows\": 18\n}\n[/block]\n\n## The `stats` object\n\nThe `stats` object contains information about interactions with this contact.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Mailing list contact stats equivalent to directory contact's stats\",\n  \"body\": \"The `stats` object documented here does not contain statistical information specific to the specified mailing list. Instead, it contains the same information as the `stats` object returned from the [Get Contact API](https://api.qualtrics.com/docs/managing-directory-contacts-for-target-audience#get-contact).\"\n}\n[/block]\nThe information contained in the `stats` object appears in the following table:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`AvgTimeToRespond`\",\n    \"0-1\": \"String\",\n    \"1-0\": \"`DataIntegrity`\",\n    \"1-1\": \"String\",\n    \"2-0\": \"`EmailCount`\",\n    \"2-1\": \"String\",\n    \"3-0\": \"`InviteCount`\",\n    \"3-1\": \"String\",\n    \"4-0\": \"`LastEmailDate`\",\n    \"4-1\": \"String\",\n    \"5-0\": \"`LastInviteDate`\",\n    \"5-1\": \"String\",\n    \"6-0\": \"`LastResponseDate`\",\n    \"6-1\": \"String\",\n    \"7-0\": \"`MonthEmailCount`\",\n    \"7-1\": \"String\",\n    \"8-0\": \"`MonthInviteCount`\",\n    \"8-1\": \"String\",\n    \"9-0\": \"`Points`\",\n    \"9-1\": \"String\",\n    \"10-0\": \"`ResponseCount`\",\n    \"10-1\": \"String\",\n    \"11-0\": \"`ResponseRate`\",\n    \"11-1\": \"String\",\n    \"0-2\": \"Average time, in hours, that passed before the contact *started* taking a survey after the invitation was sent.\",\n    \"2-2\": \"Number of emails sent to this contact since the contact was created.\",\n    \"3-2\": \"Number of invitations to take surveys that have been sent to this contact since the contact was created.\",\n    \"4-2\": \"Last date and time an email was sent to this contact. Emails include invitations to take surveys, thank you notes for taking a survey, and reminders to take a survey. The date and time is in UTC formatted as **yyyy-MM-dd HH:mm:ss**.\",\n    \"5-2\": \"Last date and time an invitation to take a survey has been sent to this contact.  The date and time is in UTC formatted as **yyyy-MM-dd HH:mm:ss**.\",\n    \"6-2\": \"Last date and time this contact completed a survey. The date and time is in UTC formatted as **yyyy-MM-dd HH:mm:ss**.\",\n    \"7-2\": \"The number of emails sent to this contact in the month that the API was called.\",\n    \"8-2\": \"The number of invitations to take surveys sent to this contact in the month that the API was called.\",\n    \"10-2\": \"Number of surveys in total that this contact completed since the contact was created.\",\n    \"11-2\": \"The ratio of surveys this contact completed compared to the total number of surveys sent. The number ranges from 0.0 to 1.0.\",\n    \"9-2\": \"The number of incentive points this contact has earned.\",\n    \"1-2\": \"The contact's data integrity score. 100 is the highest score.\"\n  },\n  \"cols\": 3,\n  \"rows\": 12\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Update Contact in Mailing List\"\n}\n[/block]\nThe Update Contact in Mailing List allows you to change data associated with a contact. \n\nThe functionality provided by this API is also provided by the Update Contact API. Update Contact API, however, does not require a mailing list ID.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Update Contact in Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_1234\\\"\\nmailingListId = \\\"CG_5678\\\"\\ncontactId = \\\"CID_3421\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}\\\".format(dataCenter, directoryId, mailingListId, contactId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\\"firstName\\\": \\\"John\\\",\\n\\t\\\"lastName\\\": \\\"Smith\\\",\\n\\t\\\"email\\\": \\\"person@example.com\\\",\\n\\t\\\"phone\\\": \\\"8005551212\\\",\\n\\t\\\"embeddedData\\\": { \\\"birthplace\\\": \\\"San Francisco, CA\\\", \\\"gender\\\": \\\"M\\\" },\\n\\t\\\"language\\\": \\\"en\\\",\\n\\t\\\"extRef\\\": \\\"12345678\\\",\\n\\t\\\"unsubscribed\\\": True\\n\\t }\\nresponse = requests.put(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response shows a successful result from this API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"2b88e3d5-4c8f-4896-ad8a-f4a2f08b41d3\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Delete Contact in Mailing List\"\n}\n[/block]\nThe Delete Contact in Mailing List API removes the specified contact from the specified mailing list. It does not remove the contact from the organization's contact directory even if the contact appears on no other mailing list.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Delete Contact in Mailing List\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456\\\"\\ncontactId = \\\"CID_1234\\\"\\nmailingListId = \\\"CG_1234567\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}\\\".format(dataCenter, directoryId, mailingListId, contactId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.delete(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nThe following response object shows the result of a successful delete:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"ed27363d-9043-4c03-b965-aba4d331cbd8\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nBecause this operation is [idempotent](https://api.qualtrics.com/docs/parameters#idempotent-requests), it returns the same 200 status code with each invocation (even after the contact has been deleted).","excerpt":"APIs for creating, getting, updating, listing, and deleting contacts on Target Audience mailing lists","slug":"managing-contacts-in-mailing-lists-for-target-audience","type":"basic","title":"Managing Contacts in Mailing Lists for Target Audience"}

Managing Contacts in Mailing Lists for Target Audience

APIs for creating, getting, updating, listing, and deleting contacts on Target Audience mailing lists

This guide contains information about using the APIs for managing contacts in mailing lists for Target Audience. For information on managing mailing lists themselves, see [Managing Mailing Lists for Target Audience](doc:managing-mailing-lists-for-target-audience). [block:callout] { "type": "warning", "title": "Target Audience Only", "body": "These APIs are only available to Target Audience users." } [/block] [block:callout] { "type": "warning", "body": "These APIs do not support actions on shared (global) mailing lists. You need to use the V2 APIs to work with global mailing lists.", "title": "Shared Mailing Lists Unsupported" } [/block] This guide covers the following APIs: - [Create Contact in Mailing List](#create-contact-in-mailing-list) - [List Contacts in Mailing List](#list-contacts-in-mailing-list) - [Get Contact in Mailing List](#get-contact-in-mailing-list) - [Update Contact in Mailing List](#update-contact-in-mailing-list) - [Delete Contact in Mailing List](#delete-contact-in-mailing-list) [block:api-header] { "title": "Create Contact in Mailing List" } [/block] This API allows you to create a new contact in the specified mailing list. This API is the only way to add a contact to a mailing list; you cannot copy a contact from the organization's contacts directory to a mailing list. When you use this API, the contact you create is also created in the organization's contacts directory. This means that if the contact already exists in the organization's contacts directory, a duplicate will be created. You can then use Target Audience's deduplication tool to remove these duplicate contacts. See [Manage Directory Duplicates](https://www.qualtrics.com/support/target-audience/directory/manage-duplicates-2/) for more information. [block:code] { "codes": [ { "code": "# Create Contact in Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_1234567\"\nmailingListId = \"CG_34567890\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts\".format(dataCenter, directoryId, mailingListId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\"firstName\": \"James\",\n\t\"lastName\": \"Smith\",\n\t\"email\": \"js@example.com\",\n\t\"phone\": \"8005552000\",\n\t\"embeddedData\": { \"level\": \"mid\", \"area\": \"coast\" },\n\t\"language\": \"en\",\n\t\"extRef\": \"1234567\",\n\t\"unsubscribed\": True,\n\t }\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following response object shows a typical result from this API: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"641ca8da-fb07-4319-907b-ab45af1a93c2\"\n },\n \"result\": {\n \"id\": \"CID_123456\"\n }\n}\n", "language": "json" } ] } [/block] [block:api-header] { "title": "List Contacts in Mailing List" } [/block] The List Contacts API returns all of the contacts on the specified mailing list. The information on each contact includes: - The contact's ID - The email address - The external reference (user-defined data attached to a contact) - The contact's first name - The contact's last name - The language (if specified) - The phone number - Whether the contact has unsubscribed ("opted-out") of the specified mailing list [block:code] { "codes": [ { "code": "# List Contacts in Mailing List\n\nimport requests\n\n# Setting user Parameters\n\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_123456\"\nmailingListId = \"CG_123456\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts\".format(dataCenter, directoryId, mailingListId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following shows an example response returned from this API: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"7de14d38-f5ed-49d0-9ff0-773e12b896b8\"\n },\n \"result\": {\n \"elements\": [\n {\n \"contactId\": \"CID_123456\",\n \"email\": \"js@example.com\",\n \"extRef\": \"1234567\",\n \"firstName\": \"James\",\n \"language\": \"en\",\n \"lastName\": \"Smith\",\n \"phone\": \"8005552000\",\n \"unsubscribed\": false\n },\n {\n \"contactId\": \"CID_3456789\",\n \"email\": \"person@example.com\",\n \"extRef\": \"12345678\",\n \"firstName\": \"John\",\n \"language\": \"en\",\n \"lastName\": \"Smith\",\n \"phone\": \"8005551212\",\n \"unsubscribed\": true\n }\n ],\n \"nextPage\": null\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "title": "Get Contact in Mailing List" } [/block] The Get Contact in Mailing List API returns information about the specified contact in the specified mailing list. The information is almost identical to the information returned by the [Get Contact API](https://api.qualtrics.com/docs/managing-directory-contacts-for-target-audience#get-contact), with two differences: 1. This API does not return mailing list membership information. 2. This API returns an ID that uniquely identifies the contact in this mailing list (`contactLookupId`). The following sample shows how to use the Get Contact in Mailing List API: [block:code] { "codes": [ { "code": "# Get Contact in Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_1234567\"\nmailingListId = \"CG_12345\"\ncontactId = \"CID_1234567\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}\".format(dataCenter, directoryId, mailingListId, contactId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)", "language": "python" } ] } [/block] The following shows an example of the response that this endpoint returns: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"7684ed69-832d-4f91-899d-d6c8aa7ccea2\"\n },\n \"result\": {\n \"contactId\": \"CID_1234567\",\n \"contactLookupId\": \"CGC_12345\",\n \"creationDate\": 1500667426000,\n \"directoryUnsubscribeDate\": null,\n \"directoryUnsubscribed\": false,\n \"email\": \"js@example.com\",\n \"emailDomain\": null,\n \"embeddedData\": {\n \"area\": \"coast\",\n \"level\": \"mid\"\n },\n \"extRef\": \"1234567\",\n \"firstName\": \"James\",\n \"language\": \"en\",\n \"lastModified\": 1500667426000,\n \"lastName\": \"Smith\",\n \"mailingListUnsubscribeDate\": null,\n \"mailingListUnsubscribed\": false,\n \"phone\": \"8005552000\",\n \"stats\": {\n \"AvgTimeToRespond\": \"0.0\",\n \"DataIntegrity\": \"100\",\n \"EmailCount\": \"1\",\n \"InviteCount\": \"1\",\n \"LastEmailDate\": \"2017-07-25 21:00:31\",\n \"LastInviteDate\": \"2017-07-25 21:00:31\",\n \"LastResponseDate\": \"2017-07-25 21:02:19\",\n \"MonthEmailCount\": \"1\",\n \"MonthInviteCount\": \"1\",\n \"Points\": \"0\",\n \"ResponseCount\": \"1\",\n \"ResponseRate\": \"1.0\"\n },\n \"writeBlanks\": false\n }\n}", "language": "json" } ] } [/block] The result contains the following data: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`contactId`", "0-1": "String", "0-2": "The contact ID.", "1-0": "`contactLookupId`", "1-1": "String", "1-2": "The contact lookup ID", "2-0": "`creationDate`", "2-1": "Number", "2-2": "Date and time this contact's record was created. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "3-0": "`directoryUnsubscribeDate`", "3-1": "Number", "4-0": "`directoryUnsubscribed`", "4-1": "Boolean", "5-0": "`email`", "5-1": "String", "6-0": "`emailDomain`", "6-1": "String", "7-0": "`embeddedData`", "7-1": "Object", "8-0": "`extRef`", "8-1": "String", "9-0": "`firstName`", "9-1": "String", "10-0": "`language`", "10-1": "String", "11-0": "`lastModified`", "11-1": "Number", "12-0": "`lastName`", "12-1": "String", "13-0": "`mailingListUnsubscribeDate`", "14-0": "`mailingListUnsubscribed`", "15-0": "`phone`", "15-1": "String", "16-0": "`stats`", "16-1": "Object", "17-0": "`writeBlanks`", "17-1": "Boolean", "7-2": "The embedded data object contains extra metadata that you want to associate with contacts. This user-defined data could include such data as birthplace, gender, employment status, etc. See [Update Contact](doc:managing-directory-contacts#update-contact) below for an example of setting the embedded data object.", "8-2": "External reference. You can place any string data here that you need to attach to a contact.", "3-2": "Date and time the user opted out of the directory. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "4-2": "Indicates whether the user opted out of the directory.", "5-2": "The contact's email address.", "6-2": "The contact's email domain.", "9-2": "The contact's first name or given name.", "10-2": "The contact's language if set.", "11-2": "Date and time this record was last modified. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "12-2": "The contact's last name or surname.", "13-2": "Date and time the user opted out of this mailing list. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "16-2": "The stats object for the contact. See the next section for information about this object.", "17-2": "Whether to write blanks.", "15-2": "The contact's phone number.", "13-1": "Number", "14-1": "Boolean", "14-2": "Whether the user has opted out of receiving email through this mailing list." }, "cols": 3, "rows": 18 } [/block] ## The `stats` object The `stats` object contains information about interactions with this contact. [block:callout] { "type": "info", "title": "Mailing list contact stats equivalent to directory contact's stats", "body": "The `stats` object documented here does not contain statistical information specific to the specified mailing list. Instead, it contains the same information as the `stats` object returned from the [Get Contact API](https://api.qualtrics.com/docs/managing-directory-contacts-for-target-audience#get-contact)." } [/block] The information contained in the `stats` object appears in the following table: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`AvgTimeToRespond`", "0-1": "String", "1-0": "`DataIntegrity`", "1-1": "String", "2-0": "`EmailCount`", "2-1": "String", "3-0": "`InviteCount`", "3-1": "String", "4-0": "`LastEmailDate`", "4-1": "String", "5-0": "`LastInviteDate`", "5-1": "String", "6-0": "`LastResponseDate`", "6-1": "String", "7-0": "`MonthEmailCount`", "7-1": "String", "8-0": "`MonthInviteCount`", "8-1": "String", "9-0": "`Points`", "9-1": "String", "10-0": "`ResponseCount`", "10-1": "String", "11-0": "`ResponseRate`", "11-1": "String", "0-2": "Average time, in hours, that passed before the contact *started* taking a survey after the invitation was sent.", "2-2": "Number of emails sent to this contact since the contact was created.", "3-2": "Number of invitations to take surveys that have been sent to this contact since the contact was created.", "4-2": "Last date and time an email was sent to this contact. Emails include invitations to take surveys, thank you notes for taking a survey, and reminders to take a survey. The date and time is in UTC formatted as **yyyy-MM-dd HH:mm:ss**.", "5-2": "Last date and time an invitation to take a survey has been sent to this contact. The date and time is in UTC formatted as **yyyy-MM-dd HH:mm:ss**.", "6-2": "Last date and time this contact completed a survey. The date and time is in UTC formatted as **yyyy-MM-dd HH:mm:ss**.", "7-2": "The number of emails sent to this contact in the month that the API was called.", "8-2": "The number of invitations to take surveys sent to this contact in the month that the API was called.", "10-2": "Number of surveys in total that this contact completed since the contact was created.", "11-2": "The ratio of surveys this contact completed compared to the total number of surveys sent. The number ranges from 0.0 to 1.0.", "9-2": "The number of incentive points this contact has earned.", "1-2": "The contact's data integrity score. 100 is the highest score." }, "cols": 3, "rows": 12 } [/block] [block:api-header] { "title": "Update Contact in Mailing List" } [/block] The Update Contact in Mailing List allows you to change data associated with a contact. The functionality provided by this API is also provided by the Update Contact API. Update Contact API, however, does not require a mailing list ID. [block:code] { "codes": [ { "code": "# Update Contact in Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_1234\"\nmailingListId = \"CG_5678\"\ncontactId = \"CID_3421\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}\".format(dataCenter, directoryId, mailingListId, contactId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = {\"firstName\": \"John\",\n\t\"lastName\": \"Smith\",\n\t\"email\": \"person@example.com\",\n\t\"phone\": \"8005551212\",\n\t\"embeddedData\": { \"birthplace\": \"San Francisco, CA\", \"gender\": \"M\" },\n\t\"language\": \"en\",\n\t\"extRef\": \"12345678\",\n\t\"unsubscribed\": True\n\t }\nresponse = requests.put(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following response shows a successful result from this API: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"2b88e3d5-4c8f-4896-ad8a-f4a2f08b41d3\"\n }\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "Delete Contact in Mailing List" } [/block] The Delete Contact in Mailing List API removes the specified contact from the specified mailing list. It does not remove the contact from the organization's contact directory even if the contact appears on no other mailing list. [block:code] { "codes": [ { "code": "# Delete Contact in Mailing List\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_123456\"\ncontactId = \"CID_1234\"\nmailingListId = \"CG_1234567\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/mailinglists/{2}/contacts/{3}\".format(dataCenter, directoryId, mailingListId, contactId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] The following response object shows the result of a successful delete: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"ed27363d-9043-4c03-b965-aba4d331cbd8\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] Because this operation is [idempotent](https://api.qualtrics.com/docs/parameters#idempotent-requests), it returns the same 200 status code with each invocation (even after the contact has been deleted).