{"_id":"594ae3201513f800100b2b91","project":"55843604fd8d910d007b9502","version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":46,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"category":{"_id":"59234825e465c11900922518","__v":0,"version":"558444ceafccfd0d00fcb2bb","project":"55843604fd8d910d007b9502","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2017-05-22T20:20:53.281Z","from_sync":false,"order":1,"slug":"using-the-qualtrics-api","title":"Using the Qualtrics APIs"},"user":"5919f13aff66b00f00f1948c","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-06-21T21:20:32.102Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"Target Audience users can use the APIs mentioned in the following guide to manage the organization's directory, which contains all of an organization's contacts. \n\nAll of the following APIs require the Target Audience directory ID (also known as a pool ID) and an account authorized for Target Audience. The directory's ID is available in the Target Audience user interface under Account Settings and Qualtrics IDs. See [Finding the Directory ID or Pool ID for Target Audience](doc:finding-qualtrics-ids#finding-the-directory-id-or-pool-id-for-target-aud).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Target Audience\",\n  \"body\": \"These APIs are only available to Target Audience users.\"\n}\n[/block]\nThis guide contains information on the following APIs:\n\n* [Create Contact](doc:managing-directory-contacts#create-contact)\n* [List Contacts](doc:managing-directory-contacts#list-contacts)\n* [Get Contact](doc:managing-directory-contacts#get-contact)\n* [Update Contact](doc:managing-directory-contacts#update-contact)\n* [Delete Contact](doc:managing-directory-contacts#delete-contact)\n[block:api-header]\n{\n  \"title\": \"Create Contact\"\n}\n[/block]\nThe Create Contact API allows you to create new contacts in the Target Audience directory. You can create a contact with the following metadata:\n\n* First name\n* Last name\n* Email address\n* Phone number\n* Language\n\nIn addition, you can create any metadata you want and attach it to the `embeddedData` object as the example below shows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create Contact\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_123456789\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts\\\".format(dataCenter, directoryId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = {\\\"firstName\\\": \\\"John\\\",\\n\\t\\\"lastName\\\": \\\"Smith\\\",\\n\\t\\\"email\\\": \\\"person:::at:::example.com\\\",\\n\\t\\\"phone\\\": \\\"8005551212\\\",\\n\\t\\\"language\\\": \\\"en\\\",\\n  \\\"embeddedData\\\": { \\\"level\\\": \\\"mid\\\", \\\"area\\\": \\\"coast\\\" },\\n\\t }\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"List Contacts\"\n}\n[/block]\nThe List Contacts API lists the current contents of the Target Audience directory. Because the collection is often large, you will probably need to paginate through the data. You can either use the `pageSize` and `offset` parameters to specify what page of the collection you'd like to view, or you can repeatedly call this API using the `nextPage` value in the results object to obtain the next page until `nextPage` is **null**.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Embedded Data\",\n  \"body\": \"The List Contacts API does not return the embedded data for each contact. You need to call [Get Contact](doc:managing-directory-contacts-for-target-audience#get-contact) on each contact for which you wish to obtain their embedded data.\"\n}\n[/block]\nThe following example shows how to use the List Contacts API with a specific offset and page size:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# List Contacts\\n\\nimport requests\\n\\n# Setting user Parameters\\n\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_12345678\\\"\\npageSize = 100\\noffset = 0\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts?pageSize={2}&offset={3}\\\".format(dataCenter, directoryId, pageSize, offset)\\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]\n\n[block:api-header]\n{\n  \"title\": \"Get Contact\"\n}\n[/block]\nThe Get Contact API returns extensive information about the specified contact. The information includes metadata about the contact (such as first name), embedded data, and statistics about the contact's survey responses and email interactions.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"This API currently does not return email history or response history as does version 2 of the Target Audience API or version 3 of the Insights Platform API.\",\n  \"title\": \"Version Information\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get Contact\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_1234567890\\\"\\ncontactId = \\\"CID_12345\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}\\\".format(dataCenter, directoryId, contactId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"bf10764c-3f2b-4bf2-8098-7be1badf7b9c\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"contactId\\\": \\\"CID_eJa3wtJLn2R0gBf\\\",\\n        \\\"creationDate\\\": 1498679121000,\\n        \\\"directoryUnsubscribeDate\\\": 1498846923000,\\n        \\\"directoryUnsubscribed\\\": true,\\n        \\\"email\\\": \\\"person@example.com\\\",\\n        \\\"emailDomain\\\": null,\\n        \\\"embeddedData\\\": {},\\n        \\\"extRef\\\": null,\\n        \\\"firstName\\\": \\\"John\\\",\\n        \\\"language\\\": \\\"en\\\",\\n        \\\"lastModified\\\": 1498679121000,\\n        \\\"lastName\\\": \\\"Smith\\\",\\n        \\\"mailingListMembership\\\": {\\n            \\\"CG_6tDFg6cUKfhiitD\\\": {\\n                \\\"contactLookupId\\\": \\\"CGC_0kOdwqXN7OTydx3\\\",\\n                \\\"name\\\": \\\"EL\\\",\\n                \\\"ownerId\\\": \\\"UR_12345678\\\",\\n                \\\"unsubscribeDate\\\": null,\\n                \\\"unsubscribed\\\": false\\n            },\\n            \\\"CG_eJLNberNOVbGhRX\\\": {\\n                \\\"contactLookupId\\\": \\\"CGC_3h4eh3L4bv7FCcd\\\",\\n                \\\"name\\\": \\\"TA\\\",\\n                \\\"ownerId\\\": \\\"UR_12345678\\\",\\n                \\\"unsubscribeDate\\\": null,\\n                \\\"unsubscribed\\\": false\\n            }\\n        },\\n        \\\"phone\\\": \\\"8005551212\\\",\\n        \\\"stats\\\": {\\n            \\\"AvgTimeToRespond\\\": \\\"0.0\\\",\\n            \\\"DataIntegrity\\\": \\\"100\\\",\\n            \\\"EmailCount\\\": \\\"2\\\",\\n            \\\"InviteCount\\\": \\\"1\\\",\\n            \\\"LastEmailDate\\\": \\\"2017-06-29 21:03:35\\\",\\n            \\\"LastInviteDate\\\": \\\"2017-06-29 19:58:45\\\",\\n            \\\"LastResponseDate\\\": \\\"2017-06-29 20:02:20\\\",\\n            \\\"MonthEmailCount\\\": \\\"2\\\",\\n            \\\"MonthInviteCount\\\": \\\"1\\\",\\n            \\\"Points\\\": \\\"0\\\",\\n            \\\"ResponseCount\\\": \\\"1\\\",\\n            \\\"ResponseRate\\\": \\\"1.0\\\"\\n        },\\n\\n        \\\"writeBlanks\\\": false\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nThe result contains the following data:\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\": \"`creationDate`\",\n    \"1-1\": \"Number\",\n    \"1-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    \"2-0\": \"`directoryUnsubscribeDate`\",\n    \"2-1\": \"Number\",\n    \"3-0\": \"`directoryUnsubscribed`\",\n    \"3-1\": \"Boolean\",\n    \"4-0\": \"`email`\",\n    \"4-1\": \"String\",\n    \"5-0\": \"`emailDomain`\",\n    \"5-1\": \"String\",\n    \"6-0\": \"`embeddedData`\",\n    \"6-1\": \"Object\",\n    \"7-0\": \"`extRef`\",\n    \"7-1\": \"String\",\n    \"8-0\": \"`firstName`\",\n    \"8-1\": \"String\",\n    \"9-0\": \"`language`\",\n    \"9-1\": \"String\",\n    \"10-0\": \"`lastModified`\",\n    \"10-1\": \"Number\",\n    \"11-0\": \"`lastName`\",\n    \"11-1\": \"String\",\n    \"12-0\": \"`mailingListMembership`\",\n    \"12-1\": \"Object\",\n    \"13-0\": \"`phone`\",\n    \"13-1\": \"String\",\n    \"14-0\": \"`stats`\",\n    \"14-1\": \"Object\",\n    \"15-0\": \"`writeBlanks`\",\n    \"15-1\": \"Boolean\",\n    \"6-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    \"7-2\": \"External reference. You can place any string data here that you need to attach to a contact.\",\n    \"2-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    \"3-2\": \"Indicates whether the user opted out of the directory.\",\n    \"4-2\": \"The contact's email address.\",\n    \"5-2\": \"The contact's email domain.\",\n    \"8-2\": \"The contact's first name or given name.\",\n    \"9-2\": \"The contact's language if set.\",\n    \"10-2\": \"Date and time this record was last modified. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.\",\n    \"11-2\": \"The contact's last name or surname.\",\n    \"12-2\": \"An object that represents the mailing lists that this contact belongs to. See \\\"Mailing List Membership\\\" below for more information.\",\n    \"13-2\": \"The contact's phone number.\",\n    \"14-2\": \"The stats object for the contact. See the next section for information about this object.\",\n    \"15-2\": \"Whether to write blanks.\"\n  },\n  \"cols\": 3,\n  \"rows\": 16\n}\n[/block]\n## The `stats` object\n\nThe `stats` object contains information about interactions with this contact as shown 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## Mailing list membership\n\nThe object `mailingListMembership` contains information about the mailing lists this contact belongs to. The object  contains objects for each mailing list. For example, this contact belongs to two mailing lists identified with CG_12345667 and CG_567890:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"        \\\"mailingListMembership\\\": {\\n            \\\"CG_12345667\\\": {\\n                \\\"contactLookupId\\\": \\\"CGC_cPkqDdd1hSpzP9z\\\",\\n                \\\"name\\\": \\\"EL\\\",\\n                \\\"ownerId\\\": \\\"UR_12345678\\\",\\n                \\\"unsubscribeDate\\\": null,\\n                \\\"unsubscribed\\\": false\\n            },\\n            \\\"CG_567890\\\": {\\n                \\\"contactLookupId\\\": \\\"CGC_bOBAmLhCg6wUATP\\\",\\n                \\\"name\\\": \\\"TA\\\",\\n                \\\"ownerId\\\": \\\"UR_12345678\\\",\\n                \\\"unsubscribeDate\\\": null,\\n                \\\"unsubscribed\\\": false\\n            }\\n        },\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\nEach `mailingListMembership` object contains the following:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"`contactLookupId`\",\n    \"0-1\": \"String\",\n    \"1-0\": \"`name`\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The name of the mailing list.\",\n    \"2-0\": \"`ownerId`\",\n    \"2-1\": \"String\",\n    \"2-2\": \"The ID of the user who owns the mailing list.\",\n    \"3-0\": \"`unsubscribeDate`\",\n    \"3-1\": \"String\",\n    \"3-2\": \"The date the contact opted out of this mailing list. Is set to `null` if the user hasn't opted out.\",\n    \"4-0\": \"`unsubscribed`\",\n    \"4-1\": \"Boolean\",\n    \"4-2\": \"Whether the contact opted out of the mailing list.\",\n    \"0-2\": \"The contact's unique ID in the mailing list.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Update Contact\"\n}\n[/block]\nThe Update Contact API allows you to change existing metadata for a contact. You can also add or update a contact's embedded data.\n\nThe example below shows how to update a contact's information and change or add embedded data:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Update Contact\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_1234567\\\"\\ncontactId = \\\"CID_1234567\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}\\\".format(dataCenter, directoryId, 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]\n\n[block:api-header]\n{\n  \"title\": \"Delete Contact\"\n}\n[/block]\nThe Delete Contact API allows you to permanently delete a contact from the organization's directory. The example below shows how to use this API:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Delete Contact\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = \\\"YOUR DATACENTER\\\"\\n\\ndirectoryId = \\\"POOL_1234567\\\"\\ncontactId = \\\"CID_123456789\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}\\\".format(dataCenter, directoryId, 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]\nA successful delete results in a 200 status code. An example response is shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"1702483a-ced4-40a5-9ade-20e01475055b\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]","excerpt":"Target Audience APIs for managing the contacts directory","slug":"managing-directory-contacts-for-target-audience","type":"basic","title":"Managing Directory Contacts for Target Audience"}

Managing Directory Contacts for Target Audience

Target Audience APIs for managing the contacts directory

Target Audience users can use the APIs mentioned in the following guide to manage the organization's directory, which contains all of an organization's contacts. All of the following APIs require the Target Audience directory ID (also known as a pool ID) and an account authorized for Target Audience. The directory's ID is available in the Target Audience user interface under Account Settings and Qualtrics IDs. See [Finding the Directory ID or Pool ID for Target Audience](doc:finding-qualtrics-ids#finding-the-directory-id-or-pool-id-for-target-aud). [block:callout] { "type": "info", "title": "Target Audience", "body": "These APIs are only available to Target Audience users." } [/block] This guide contains information on the following APIs: * [Create Contact](doc:managing-directory-contacts#create-contact) * [List Contacts](doc:managing-directory-contacts#list-contacts) * [Get Contact](doc:managing-directory-contacts#get-contact) * [Update Contact](doc:managing-directory-contacts#update-contact) * [Delete Contact](doc:managing-directory-contacts#delete-contact) [block:api-header] { "title": "Create Contact" } [/block] The Create Contact API allows you to create new contacts in the Target Audience directory. You can create a contact with the following metadata: * First name * Last name * Email address * Phone number * Language In addition, you can create any metadata you want and attach it to the `embeddedData` object as the example below shows: [block:code] { "codes": [ { "code": "# Create Contact\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_123456789\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts\".format(dataCenter, directoryId)\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\"language\": \"en\",\n \"embeddedData\": { \"level\": \"mid\", \"area\": \"coast\" },\n\t }\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python" } ] } [/block] [block:api-header] { "title": "List Contacts" } [/block] The List Contacts API lists the current contents of the Target Audience directory. Because the collection is often large, you will probably need to paginate through the data. You can either use the `pageSize` and `offset` parameters to specify what page of the collection you'd like to view, or you can repeatedly call this API using the `nextPage` value in the results object to obtain the next page until `nextPage` is **null**. [block:callout] { "type": "info", "title": "Embedded Data", "body": "The List Contacts API does not return the embedded data for each contact. You need to call [Get Contact](doc:managing-directory-contacts-for-target-audience#get-contact) on each contact for which you wish to obtain their embedded data." } [/block] The following example shows how to use the List Contacts API with a specific offset and page size: [block:code] { "codes": [ { "code": "# List Contacts\n\nimport requests\n\n# Setting user Parameters\n\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_12345678\"\npageSize = 100\noffset = 0\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts?pageSize={2}&offset={3}\".format(dataCenter, directoryId, pageSize, offset)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] [block:api-header] { "title": "Get Contact" } [/block] The Get Contact API returns extensive information about the specified contact. The information includes metadata about the contact (such as first name), embedded data, and statistics about the contact's survey responses and email interactions. [block:callout] { "type": "info", "body": "This API currently does not return email history or response history as does version 2 of the Target Audience API or version 3 of the Insights Platform API.", "title": "Version Information" } [/block] [block:code] { "codes": [ { "code": "# Get Contact\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_1234567890\"\ncontactId = \"CID_12345\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}\".format(dataCenter, directoryId, contactId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python" } ] } [/block] [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"bf10764c-3f2b-4bf2-8098-7be1badf7b9c\"\n },\n \"result\": {\n \"contactId\": \"CID_eJa3wtJLn2R0gBf\",\n \"creationDate\": 1498679121000,\n \"directoryUnsubscribeDate\": 1498846923000,\n \"directoryUnsubscribed\": true,\n \"email\": \"person@example.com\",\n \"emailDomain\": null,\n \"embeddedData\": {},\n \"extRef\": null,\n \"firstName\": \"John\",\n \"language\": \"en\",\n \"lastModified\": 1498679121000,\n \"lastName\": \"Smith\",\n \"mailingListMembership\": {\n \"CG_6tDFg6cUKfhiitD\": {\n \"contactLookupId\": \"CGC_0kOdwqXN7OTydx3\",\n \"name\": \"EL\",\n \"ownerId\": \"UR_12345678\",\n \"unsubscribeDate\": null,\n \"unsubscribed\": false\n },\n \"CG_eJLNberNOVbGhRX\": {\n \"contactLookupId\": \"CGC_3h4eh3L4bv7FCcd\",\n \"name\": \"TA\",\n \"ownerId\": \"UR_12345678\",\n \"unsubscribeDate\": null,\n \"unsubscribed\": false\n }\n },\n \"phone\": \"8005551212\",\n \"stats\": {\n \"AvgTimeToRespond\": \"0.0\",\n \"DataIntegrity\": \"100\",\n \"EmailCount\": \"2\",\n \"InviteCount\": \"1\",\n \"LastEmailDate\": \"2017-06-29 21:03:35\",\n \"LastInviteDate\": \"2017-06-29 19:58:45\",\n \"LastResponseDate\": \"2017-06-29 20:02:20\",\n \"MonthEmailCount\": \"2\",\n \"MonthInviteCount\": \"1\",\n \"Points\": \"0\",\n \"ResponseCount\": \"1\",\n \"ResponseRate\": \"1.0\"\n },\n\n \"writeBlanks\": false\n }\n}\n", "language": "json", "name": "Response" } ] } [/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": "`creationDate`", "1-1": "Number", "1-2": "Date and time this contact's record was created. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "2-0": "`directoryUnsubscribeDate`", "2-1": "Number", "3-0": "`directoryUnsubscribed`", "3-1": "Boolean", "4-0": "`email`", "4-1": "String", "5-0": "`emailDomain`", "5-1": "String", "6-0": "`embeddedData`", "6-1": "Object", "7-0": "`extRef`", "7-1": "String", "8-0": "`firstName`", "8-1": "String", "9-0": "`language`", "9-1": "String", "10-0": "`lastModified`", "10-1": "Number", "11-0": "`lastName`", "11-1": "String", "12-0": "`mailingListMembership`", "12-1": "Object", "13-0": "`phone`", "13-1": "String", "14-0": "`stats`", "14-1": "Object", "15-0": "`writeBlanks`", "15-1": "Boolean", "6-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.", "7-2": "External reference. You can place any string data here that you need to attach to a contact.", "2-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.", "3-2": "Indicates whether the user opted out of the directory.", "4-2": "The contact's email address.", "5-2": "The contact's email domain.", "8-2": "The contact's first name or given name.", "9-2": "The contact's language if set.", "10-2": "Date and time this record was last modified. Expressed in *milliseconds* since the Unix epoch, January 1, 1970 at 0:00 UTC.", "11-2": "The contact's last name or surname.", "12-2": "An object that represents the mailing lists that this contact belongs to. See \"Mailing List Membership\" below for more information.", "13-2": "The contact's phone number.", "14-2": "The stats object for the contact. See the next section for information about this object.", "15-2": "Whether to write blanks." }, "cols": 3, "rows": 16 } [/block] ## The `stats` object The `stats` object contains information about interactions with this contact as shown 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] ## Mailing list membership The object `mailingListMembership` contains information about the mailing lists this contact belongs to. The object contains objects for each mailing list. For example, this contact belongs to two mailing lists identified with CG_12345667 and CG_567890: [block:code] { "codes": [ { "code": " \"mailingListMembership\": {\n \"CG_12345667\": {\n \"contactLookupId\": \"CGC_cPkqDdd1hSpzP9z\",\n \"name\": \"EL\",\n \"ownerId\": \"UR_12345678\",\n \"unsubscribeDate\": null,\n \"unsubscribed\": false\n },\n \"CG_567890\": {\n \"contactLookupId\": \"CGC_bOBAmLhCg6wUATP\",\n \"name\": \"TA\",\n \"ownerId\": \"UR_12345678\",\n \"unsubscribeDate\": null,\n \"unsubscribed\": false\n }\n },\n", "language": "json", "name": "Response" } ] } [/block] Each `mailingListMembership` object contains the following: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "`contactLookupId`", "0-1": "String", "1-0": "`name`", "1-1": "String", "1-2": "The name of the mailing list.", "2-0": "`ownerId`", "2-1": "String", "2-2": "The ID of the user who owns the mailing list.", "3-0": "`unsubscribeDate`", "3-1": "String", "3-2": "The date the contact opted out of this mailing list. Is set to `null` if the user hasn't opted out.", "4-0": "`unsubscribed`", "4-1": "Boolean", "4-2": "Whether the contact opted out of the mailing list.", "0-2": "The contact's unique ID in the mailing list." }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "title": "Update Contact" } [/block] The Update Contact API allows you to change existing metadata for a contact. You can also add or update a contact's embedded data. The example below shows how to update a contact's information and change or add embedded data: [block:code] { "codes": [ { "code": "# Update Contact\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_1234567\"\ncontactId = \"CID_1234567\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}\".format(dataCenter, directoryId, 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] [block:api-header] { "title": "Delete Contact" } [/block] The Delete Contact API allows you to permanently delete a contact from the organization's directory. The example below shows how to use this API: [block:code] { "codes": [ { "code": "# Delete Contact\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = \"YOUR DATACENTER\"\n\ndirectoryId = \"POOL_1234567\"\ncontactId = \"CID_123456789\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/directories/{1}/contacts/{2}\".format(dataCenter, directoryId, contactId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python" } ] } [/block] A successful delete results in a 200 status code. An example response is shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"1702483a-ced4-40a5-9ade-20e01475055b\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block]