Import Users via API & Google Sheets
Import Users via API & Google Sheets
Out of the box, Zendesk has a user import feature but it is limited when either creating new users or updating existing ones.
Here's a quick comparison of what can be imported via the Admin screen versus the API.
Comparison table of Zendesk’s UI Import versus using the API
So what if you want to import common attributes such as language, time zone or any other field in red without buying an app from the Marketplace?
This article will guide you through importing bulk users to your Zendesk instance with all of the available attributes in the API using only Google Sheets (which is free!).
You'll be importing users in under 15 minutes.
Generate API Key
You'll need an API key to allow you script access to your Zendesk instance. You can revoke it later if you like.
Open Zendesk Admin Center
Navigate to Apps & Integrations > Zendesk API
Click Add API Token
Give it a descriptive name
Copy the key to your clipboard and save it somewhere securely like a password manager
Click Save. You'll need this key later.
Create Google Sheet
Two options:
You can either download a CSV template from here: Zendesk_User_Import_Template and open it in Google Sheets, or
create your own Google Sheet from scratch using the field names in the table below.
Zendesk API User Fields & Descriptions
💁🏽 Pro Tip
Zendesk has a limit of 100 rows per import BUT our script has thought of this too so go ahead and paste in as many rows as you need.
Create Your Script
From within your Google Sheets file click Extensions > Apps Script
Give your project a name
Copy the following script to your clipboard
function importUsersToZendesk() {
var subdomain = 'your_subdomain'; // Replace with your Zendesk subdomain
var email = 'your_email'; // Replace with your Zendesk email
var apiToken = 'your_api_token'; // Replace with your Zendesk API token
var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();
var data = sheet.getDataRange().getValues();
var headers = data[0];
var users = [];
var orgCache = {};
// Collect user data and map organization names to IDs
for (var i = 1; i < data.length; i++) {
var user = {};
for (var j = 0; j < headers.length; j++) {
if (data[i][j] !== '') {
if (headers[j] === 'organization') {
var orgName = data[i][j];
if (!orgCache[orgName]) {
var orgId = getOrCreateOrganization(subdomain, email, apiToken, orgName);
orgCache[orgName] = orgId;
}
user.organization_id = orgCache[orgName];
} else {
user[headers[j]] = data[i][j];
}
}
}
users.push(user);
}
// Split users into batches of 100
var batches = [];
while (users.length) {
batches.push(users.splice(0, 100));
}
// Import users in batches
batches.forEach(function(batch, index) {
var url = 'https://' + subdomain + '.zendesk.com/api/v2/users/create_many.json';
var options = {
"method": "post",
"headers": {
"Authorization": "Basic " + Utilities.base64Encode(email + '/token:' + apiToken),
"Content-Type": "application/json"
},
"payload": JSON.stringify({"users": batch})
};
try {
var response = UrlFetchApp.fetch(url, options);
var responseData = JSON.parse(response.getContentText());
if (response.getResponseCode() == 201) {
Logger.log('Batch ' + (index + 1) + ' of ' + batches.length + ' imported successfully.');
} else {
Logger.log('Message: ' + (index + 1) + '. Response: ' + response.getContentText());
}
} catch (e) {
Logger.log('Encountered an error importing batch ' + (index + 1) + ': ' + e.message);
}
});
Logger.log('User import process completed.');
}
function getOrCreateOrganization(subdomain, email, apiToken, orgName) {
var url = 'https://' + subdomain + '.zendesk.com/api/v2/organizations/search.json?name=' + encodeURIComponent(orgName);
var options = {
"method": "get",
"headers": {
"Authorization": "Basic " + Utilities.base64Encode(email + '/token:' + apiToken),
"Content-Type": "application/json"
}
};
try {
var response = UrlFetchApp.fetch(url, options);
var responseData = JSON.parse(response.getContentText());
if (responseData.organizations.length === 0) {
// Organization does not exist, create it
var createUrl = 'https://' + subdomain + '.zendesk.com/api/v2/organizations.json';
var createOptions = {
"method": "post",
"headers": {
"Authorization": "Basic " + Utilities.base64Encode(email + '/token:' + apiToken),
"Content-Type": "application/json"
},
"payload": JSON.stringify({
"organization": {
"name": orgName
}
})
};
var createResponse = UrlFetchApp.fetch(createUrl, createOptions);
var createResponseData = JSON.parse(createResponse.getContentText());
if (createResponse.getResponseCode() == 201) {
Logger.log('Organization ' + orgName + ' created successfully.');
return createResponseData.organization.id;
} else {
Logger.log('Failed to create organization ' + orgName + '. Response: ' + createResponse.getContentText());
return null;
}
} else {
Logger.log('Organization ' + orgName + ' already exists.');
return responseData.organizations[0].id;
}
} catch (e) {
Logger.log('Encountered an error checking/creating organization ' + orgName + ': ' + e.message);
return null;
}
}
4. Paste your script into the main window ensuring you overwrite anything already in that window
5. Replace the text 'your_subdomain' with your actual sub-domain. You can find your sub-domain in Admin Center > Brand
6. Replace the text 'your_email' with your Zendesk administrator email
7. Replace the text 'your_api_token' with the API token you created above
8. Click the Save icon
9. Click Run - you’ll be prompted to Review Permissions
10. Choose your Google account - you need to authorise that your Google account where the script and Google Sheet are stored can access your Zendesk data
This warning is because you're about to let the script execute on your Google Account.
11. You may or may not receive a warning. If you do, click Advanced
Click Go to My Zendesk User Import Script (unsafe)
12. Click Go to My Zendesk User Import Script (unsafe) - or whatever you named your script and click Allow
Google Access Permission
13. Your script will run now and you should see an Execution Log beneath the script
Execution Log
14. You can check the final status of the job by copying/pasting the URL from the log into a new browser window. Mostly though you can just switch to your Zendesk agent workspace and locate the new user(s)
To Recap
Zendesk’s UI import is limited in the fields it can import. To do a more comprehensive import you can use this script combined with Google Sheets. It’s flexible, fairly easy to understand and will save you from purchasing 3rd party tools.