{"_id":"59276388c385770f0011579e","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"},"__v":0,"version":{"_id":"558444ceafccfd0d00fcb2bb","forked_from":"55843604fd8d910d007b9505","project":"55843604fd8d910d007b9502","__v":55,"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"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"3.0.0","version":"3"},"project":"55843604fd8d910d007b9502","parentDoc":null,"user":"5919f13aff66b00f00f1948c","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-05-25T23:06:48.079Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"The Qualtrics APIs for managing users allow you to get information about a specific user, list all users, create a new user, update a user's attributes, and delete a user.\n\nThe following APIs are discussed:\n\n* [Get User](doc:managing-users#get-user) \n* [List Users](doc:managing-users#list-users) \n* [Create User](doc:managing-users#create-user) \n* [Update User](doc:managing-users#update-user) \n* [Delete User](doc:managing-users#delete-user) \n[block:api-header]\n{\n  \"title\": \"Get User\"\n}\n[/block]\nThe Get User API allows you to retrieve information about a user. User information can be edited in the Admin area of the Qualtrics user interface. See [Creating and Managing Users](https://www.qualtrics.com/support/survey-platform/sp-administration/managing-users/creating-and-managing-users/) for more information.\n\nThe following example shows how to request user info for the specified user:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Get User\\n\\nimport requests\\n\\n# Setting user parameters\\napiToken = \\\"YOUR API TOKEN\\\" # 1\\ndataCenter = \\\"YOUR DATACENTER\\\" # 2\\n\\nuserId = \\\"USER ID TO LOOK UP\\\" # 3\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/users/{1}\\\".format(dataCenter, userId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python 3\"\n    }\n  ]\n}\n[/block]\nThe response JSON object contains the following members that describe the user:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Member\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-0\": \"accountCreationDate\",\n    \"0-1\": \"String\",\n    \"0-2\": \"The date and time that the account was created. Dates and times are expressed in ISO 8601 format (see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)).\",\n    \"1-0\": \"accountExpirationDate\",\n    \"1-1\": \"String\",\n    \"1-2\": \"The date the account expires. Dates and times are expressed in ISO 8601 format (see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)).\",\n    \"2-0\": \"divisionId\",\n    \"2-1\": \"String\",\n    \"2-2\": \"The user's division ID or ```null``` if there is no division ID.\",\n    \"3-0\": \"email\",\n    \"3-1\": \"String\",\n    \"3-2\": \"The user's email address.\",\n    \"4-0\": \"firstName\",\n    \"4-1\": \"String\",\n    \"4-2\": \"The user's first name or given name.\",\n    \"5-0\": \"id\",\n    \"5-1\": \"String\",\n    \"5-2\": \"The user ID.\",\n    \"6-0\": \"language\",\n    \"6-1\": \"String\",\n    \"6-2\": \"The user's default language.\",\n    \"7-0\": \"lastLoginDate\",\n    \"7-1\": \"String\",\n    \"7-2\": \"The date and time the user last logged into the user interface. Dates and times are expressed in ISO 8601 format (see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)).\",\n    \"8-0\": \"lastName\",\n    \"8-1\": \"String\",\n    \"8-2\": \"The user's last name or surname.\",\n    \"9-0\": \"organizationId\",\n    \"9-1\": \"String\",\n    \"9-2\": \"The user's organization ID. This is the same name that you used for API requests: ```organizationId```.qualtrics.com.\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\nIf you do not have permissions to access to the user's data, you will receive a 401 response as shown below:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"error\\\": {\\n            \\\"errorCode\\\": \\\"UJC_3\\\",\\n            \\\"errorMessage\\\": \\\"You do not have read access on this user data.\\\"\\n        },\\n        \\\"httpStatus\\\": \\\"401 - Unauthorized\\\",\\n        \\\"requestId\\\": null\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"401 Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"List Users\"\n}\n[/block]\nThe List Users API returns information about the user collection on your site. You need to be a brand administrator to retrieve user information.\n\nThe following sample shows how to retrieve the user collection: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# List Users\\n\\nimport requests\\n\\n#Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\"\\ndataCenter = 'YOUR DATACENTER'\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/users\\\".format(dataCenter)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.get(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python 3\"\n    }\n  ]\n}\n[/block]\nThe returned response contains an array of the users in the data center as the following JSON object shows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"b84c6dd7-9223-4003-9744-ed72f3ea7b83\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"elements\\\": [\\n            {\\n                \\\"accountStatus\\\": \\\"active\\\",\\n                \\\"divisionId\\\": null,\\n                \\\"email\\\": \\\"person:::at:::example.com\\\",\\n                \\\"firstName\\\": \\\"John\\\",\\n                \\\"id\\\": \\\"UR_1234567890\\\",\\n                \\\"lastName\\\": \\\"Smith\\\",\\n                \\\"userType\\\": \\\"UT_12345678\\\",\\n                \\\"username\\\": \\\"person@example.com\\\"\\n            },\\n            {\\n                \\\"accountStatus\\\": \\\"active\\\",\\n                \\\"divisionId\\\": null,\\n                \\\"email\\\": \\\"person2@example.com\\\",\\n                \\\"firstName\\\": \\\"Jane\\\",\\n                \\\"id\\\": \\\"UR_9876543210\\\",\\n                \\\"lastName\\\": \\\"Doe\\\",\\n                \\\"userType\\\": \\\"UT_76890123\\\",\\n                \\\"username\\\": \\\"person2@example.com\\\"\\n            },\\n\\n        ],\\n        \\\"nextPage\\\": null\\n    }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nSee the table under [Get User](doc:managing-users#get-user) for more information about the attributes returned for each user. \n[block:api-header]\n{\n  \"title\": \"Create User\"\n}\n[/block]\nThe Create User API allows you to create a new user with the specified attributes. The parameters you are **required** to specify include:\n\n- Username\n- Password\n- First name\n- Last name\n- User type (see [User Types](https://www.qualtrics.com/support/survey-platform/sp-administration/managing-users/user-types/) for more information about creating and using user types.)\n- Email address\n- Language (see [Language Codes](doc:language-codes) for available language codes.)\n\nOptional parameters include:\n\n- Division ID\n- Account expiration date\n\nThe table under [Get User](doc:managing-users#get-user) has more information about these attributes.\n\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Create User \\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\" # 1\\ndataCenter = \\\"YOUR DATACENTER\\\"\\t# 2\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/users\\\".format(dataCenter)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = { \\\"username\\\": \\\"person@example.com\\\",\\n\\t\\\"password\\\": \\\"aPassword\\\",\\n\\t\\\"firstName\\\": \\\"John\\\",\\n\\t\\\"lastName\\\": \\\"Smith\\\",\\n\\t\\\"userType\\\": \\\"UT_123456789\\\",\\n\\t\\\"email\\\": \\\"person@example.com\\\",\\n\\t\\\"language\\\": \\\"en\\\",\\n\\t }\\nresponse = requests.post(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python 3\"\n    }\n  ]\n}\n[/block]\nThe response object includes the new user's ID:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"meta\\\": {\\n        \\\"httpStatus\\\": \\\"200 - OK\\\",\\n        \\\"requestId\\\": \\\"d121c1a0-c86e-4bba-8594-ddfcee1569a1\\\"\\n    },\\n    \\\"result\\\": {\\n        \\\"id\\\": \\\"UR_1234567890\\\"\\n    }\\n}\\n\",\n      \"language\": \"json\",\n      \"name\": \"Response\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Update User\"\n}\n[/block]\nThe Update User API lets you change certain user attributes. All attributes are optional and include:\n\n- User name\n- Password\n- First name\n- Last name\n- User type\n- Division ID\n- Status (active, disabled, notVerified)\n- Language\n- Permissions\n- Account expiration date\n\nThe only parameter that is required is the user ID, and it is specified in the URL.\n\nThe following example shows how to change a user's first name:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Update User\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\" # 1\\ndataCenter = \\\"YOUR DATACENTER\\\"\\t# 2\\nuserId = \\\"UR_1234567890\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/users/{1}\\\".format(dataCenter, userId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    \\\"Content-Type\\\": \\\"application/json\\\"\\n    }\\n\\ndata = { \\n\\t\\\"firstName\\\": \\\"Joe\\\",\\n\\t }\\nresponse = requests.put(baseUrl, json=data, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python 3\"\n    }\n  ]\n}\n[/block]\nA successful update results in a 200 status code.\n[block:api-header]\n{\n  \"title\": \"Delete User\"\n}\n[/block]\nThe Delete User API deletes the specified user, but it requires brand administrator permissions.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# Delete User\\n\\nimport requests\\n\\n# Setting user Parameters\\napiToken = \\\"YOUR API TOKEN\\\" # 1\\ndataCenter = \\\"YOUR DATACENTER\\\"\\t# 2\\nuserId = \\\"UR_1234567890\\\"\\n\\nbaseUrl = \\\"https://{0}.qualtrics.com/API/v3/users/{1}\\\".format(dataCenter, userId)\\nheaders = {\\n    \\\"x-api-token\\\": apiToken,\\n    }\\n\\nresponse = requests.delete(baseUrl, headers=headers)\\nprint(response.text)\\n\",\n      \"language\": \"python\",\n      \"name\": \"Python 3\"\n    }\n  ]\n}\n[/block]\nA successful delete results in a 200 status code.","excerpt":"APIs for managing your users","slug":"managing-users","type":"basic","title":"Managing Users"}

Managing Users

APIs for managing your users

The Qualtrics APIs for managing users allow you to get information about a specific user, list all users, create a new user, update a user's attributes, and delete a user. The following APIs are discussed: * [Get User](doc:managing-users#get-user) * [List Users](doc:managing-users#list-users) * [Create User](doc:managing-users#create-user) * [Update User](doc:managing-users#update-user) * [Delete User](doc:managing-users#delete-user) [block:api-header] { "title": "Get User" } [/block] The Get User API allows you to retrieve information about a user. User information can be edited in the Admin area of the Qualtrics user interface. See [Creating and Managing Users](https://www.qualtrics.com/support/survey-platform/sp-administration/managing-users/creating-and-managing-users/) for more information. The following example shows how to request user info for the specified user: [block:code] { "codes": [ { "code": "# Get User\n\nimport requests\n\n# Setting user parameters\napiToken = \"YOUR API TOKEN\" # 1\ndataCenter = \"YOUR DATACENTER\" # 2\n\nuserId = \"USER ID TO LOOK UP\" # 3\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/users/{1}\".format(dataCenter, userId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python 3" } ] } [/block] The response JSON object contains the following members that describe the user: [block:parameters] { "data": { "h-0": "Member", "h-1": "Type", "h-2": "Description", "0-0": "accountCreationDate", "0-1": "String", "0-2": "The date and time that the account was created. Dates and times are expressed in ISO 8601 format (see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)).", "1-0": "accountExpirationDate", "1-1": "String", "1-2": "The date the account expires. Dates and times are expressed in ISO 8601 format (see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)).", "2-0": "divisionId", "2-1": "String", "2-2": "The user's division ID or ```null``` if there is no division ID.", "3-0": "email", "3-1": "String", "3-2": "The user's email address.", "4-0": "firstName", "4-1": "String", "4-2": "The user's first name or given name.", "5-0": "id", "5-1": "String", "5-2": "The user ID.", "6-0": "language", "6-1": "String", "6-2": "The user's default language.", "7-0": "lastLoginDate", "7-1": "String", "7-2": "The date and time the user last logged into the user interface. Dates and times are expressed in ISO 8601 format (see [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)).", "8-0": "lastName", "8-1": "String", "8-2": "The user's last name or surname.", "9-0": "organizationId", "9-1": "String", "9-2": "The user's organization ID. This is the same name that you used for API requests: ```organizationId```.qualtrics.com." }, "cols": 3, "rows": 10 } [/block] If you do not have permissions to access to the user's data, you will receive a 401 response as shown below: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"error\": {\n \"errorCode\": \"UJC_3\",\n \"errorMessage\": \"You do not have read access on this user data.\"\n },\n \"httpStatus\": \"401 - Unauthorized\",\n \"requestId\": null\n }\n}\n", "language": "json", "name": "401 Response" } ] } [/block] [block:api-header] { "title": "List Users" } [/block] The List Users API returns information about the user collection on your site. You need to be a brand administrator to retrieve user information. The following sample shows how to retrieve the user collection: [block:code] { "codes": [ { "code": "# List Users\n\nimport requests\n\n#Setting user Parameters\napiToken = \"YOUR API TOKEN\"\ndataCenter = 'YOUR DATACENTER'\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/users\".format(dataCenter)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.get(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python 3" } ] } [/block] The returned response contains an array of the users in the data center as the following JSON object shows: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"b84c6dd7-9223-4003-9744-ed72f3ea7b83\"\n },\n \"result\": {\n \"elements\": [\n {\n \"accountStatus\": \"active\",\n \"divisionId\": null,\n \"email\": \"person@example.com\",\n \"firstName\": \"John\",\n \"id\": \"UR_1234567890\",\n \"lastName\": \"Smith\",\n \"userType\": \"UT_12345678\",\n \"username\": \"person@example.com\"\n },\n {\n \"accountStatus\": \"active\",\n \"divisionId\": null,\n \"email\": \"person2@example.com\",\n \"firstName\": \"Jane\",\n \"id\": \"UR_9876543210\",\n \"lastName\": \"Doe\",\n \"userType\": \"UT_76890123\",\n \"username\": \"person2@example.com\"\n },\n\n ],\n \"nextPage\": null\n }\n}\n", "language": "json" } ] } [/block] See the table under [Get User](doc:managing-users#get-user) for more information about the attributes returned for each user. [block:api-header] { "title": "Create User" } [/block] The Create User API allows you to create a new user with the specified attributes. The parameters you are **required** to specify include: - Username - Password - First name - Last name - User type (see [User Types](https://www.qualtrics.com/support/survey-platform/sp-administration/managing-users/user-types/) for more information about creating and using user types.) - Email address - Language (see [Language Codes](doc:language-codes) for available language codes.) Optional parameters include: - Division ID - Account expiration date The table under [Get User](doc:managing-users#get-user) has more information about these attributes. [block:code] { "codes": [ { "code": "# Create User \n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\" # 1\ndataCenter = \"YOUR DATACENTER\"\t# 2\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/users\".format(dataCenter)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = { \"username\": \"person@example.com\",\n\t\"password\": \"aPassword\",\n\t\"firstName\": \"John\",\n\t\"lastName\": \"Smith\",\n\t\"userType\": \"UT_123456789\",\n\t\"email\": \"person@example.com\",\n\t\"language\": \"en\",\n\t }\nresponse = requests.post(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python 3" } ] } [/block] The response object includes the new user's ID: [block:code] { "codes": [ { "code": "{\n \"meta\": {\n \"httpStatus\": \"200 - OK\",\n \"requestId\": \"d121c1a0-c86e-4bba-8594-ddfcee1569a1\"\n },\n \"result\": {\n \"id\": \"UR_1234567890\"\n }\n}\n", "language": "json", "name": "Response" } ] } [/block] [block:api-header] { "title": "Update User" } [/block] The Update User API lets you change certain user attributes. All attributes are optional and include: - User name - Password - First name - Last name - User type - Division ID - Status (active, disabled, notVerified) - Language - Permissions - Account expiration date The only parameter that is required is the user ID, and it is specified in the URL. The following example shows how to change a user's first name: [block:code] { "codes": [ { "code": "# Update User\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\" # 1\ndataCenter = \"YOUR DATACENTER\"\t# 2\nuserId = \"UR_1234567890\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/users/{1}\".format(dataCenter, userId)\nheaders = {\n \"x-api-token\": apiToken,\n \"Content-Type\": \"application/json\"\n }\n\ndata = { \n\t\"firstName\": \"Joe\",\n\t }\nresponse = requests.put(baseUrl, json=data, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python 3" } ] } [/block] A successful update results in a 200 status code. [block:api-header] { "title": "Delete User" } [/block] The Delete User API deletes the specified user, but it requires brand administrator permissions. [block:code] { "codes": [ { "code": "# Delete User\n\nimport requests\n\n# Setting user Parameters\napiToken = \"YOUR API TOKEN\" # 1\ndataCenter = \"YOUR DATACENTER\"\t# 2\nuserId = \"UR_1234567890\"\n\nbaseUrl = \"https://{0}.qualtrics.com/API/v3/users/{1}\".format(dataCenter, userId)\nheaders = {\n \"x-api-token\": apiToken,\n }\n\nresponse = requests.delete(baseUrl, headers=headers)\nprint(response.text)\n", "language": "python", "name": "Python 3" } ] } [/block] A successful delete results in a 200 status code.