User APIs

Users are the end users of your product or service who access your help center to find solutions.

Get all users

Use this API to get the list of all users:

GET https://id360.manageengine.com/api/v1/users

Scopes- idmpod.users.ALL & idmpod.user.READ

Parameters

cursor String Specifies the pagination for the next page of users. The cursor obtained from the previous response will be used for the current request. For initial requests, it shall not be provided.
limit number The total number of users to be obtained. By default, it's 200, and the maximum limit is also 200.
fields String Specify the attribute names that have to be displayed in the result list. Attributes names are separated by a comma.E.g., firstName,userName

Response

Success

Response Code - 200

{
	"data": [
		{
			 "lastName": "Hales",
			 "country": "US",
			 "zipPostal": "99501",
			 "gender": "M",
			 "city": "Anchorage",
			 "mobileNumber": "7700900461",
			 "displayName": "AlexHales",
			 "description": "User of marketing department",
			 "stateProvince": "Alaska",
			 "employeeID": "12342",
			 "language": "en",
			 "workLocation": "Alaska",
			 "firstName": "Alex",
			 "street": "19th Ave, Anchorage, Alaska",
			 "id": "2000000000001",
			 "isDomainVerified": "false",
			 "email": "alexhales@company.com",
			 "status": 1
		},
		{
			 "lastName": "Raymond",
			 "country": "US",
			 "zipPostal": "90001",
			 "gender": "M",
			 "city": "Los Angeles",
			 "mobileNumber": "7304729472",
			 "displayName": "JohnRay",
			 "description": "User of sales department",
			 "stateProvince": "California",
			 "employeeID": "13894",
			 "language": "en",
			 "workLocation": "California",
			 "firstName": "John",
			 "street": "Mckinley Ave, Los Angeled, California",
			 "id": "2000000000002",
			 "isDomainVerified": "false",
			 "email": "johnray@company.com",
			 "status": 1
		}
	 ],
	 "meta" : {
		 "cursor": "MzAwMDAwMDA3NjM3Mw==",
		 "next_cursor": "MjAwMDAwMDA3NzYzNA==",
		 "is_last": true,
		 "limit": 2,
		 "total_no_of_objects": 2345
	 }
}

Failure

Response code - <error-response-code>

{
	"error": {
		 "code": ,
		 "detail": ,
		 "title": 
	 }
}

Get user

Use this API to get user details.

Use this API to get user details in the Universal Directory:
GET https://id360.manageengine.com/api/v1/users/<user_id>

Scope - idmpod.user.ALL OR idmpod.user.READ

Parameters

fields string Specifies the attribute name that has to be displayed in the result list. Attributes names are separated by a comma.E.g. firstName, userName

Response

For this API, all supported attributes will be returned as default if no selected attributes are given.

Success

Response Code - 200

{
	"data": {
		"lastName": "Hales",
		"country": "US"
		"telephoneNumber": "9072746922",
		"zipPostal": "99501",
		"gender": "M",
		"city": "Anchorage",
		"mobileNumber": "7700900461",
		"displayName": "AlexHales",
		"description": "User of marketing department",
		"employeeID": "12342",
		"language": "en",
		"title": "Manager",
		"manager": "2000000072269",
		"workLocation": "Alaska",
		"postOfficeBox": "1052",
		"street": "19th Ave, Anchorage, Alaska",
		"seatingLocation": "5LC12",
		"company": "Berge Corporation",
		"id": "2000000000001",
		"isDomainVerified": "false",
		"fax": "441619998888",
		"email": "alexhales@company.com",
		"homePhone": "044-24681357",
		"stateProvince": "Alaska",
		"firstName": "Alex",
		"status": 1,
		"primarySource": {
			"modifiedTime": "2023-12-12T14:32:50+05:30",
			"applicationService": {
				"name": "Universal Directory",
				"logo": "universal-directory",
				"id": "2000000018007",
				"serviceName": "ZOHO_DIRECTORY"
			},
			"creationTime": "2023-12-12T14:32:50+05:30",
			"isEnabled": true,
			"id": "2000000072637",
			"applicationName": "Berge-Corp"
		}
	}
}

Failure

Response code - <error-response-code>

{
	"error": {
		   "code": ,
		   "detail": ,
		   "title": 
	   }
}

Enable user

Use this API to enable a user.

Use this API to enable a user in its primary directory and Universal Directory :
POST https://id360.manageengine.com/api/v1/users/<user_id>/enable

Scope - idmpod.user.ALL OR idmpod.user.WRITE OR idmpod.user.UPDATE

Response

Success

Response Code - 204

Failure

Response code - <error-response-code>

{
	"error": {
	   "code": <error-code>,
	   "detail": <error-detail>,
	   "title": <error-title>
   }
}

Disable user

Use this API to disable a user.

Use this API to disable a user in its primary directory and Universal Directory:
POST https://id360.manageengine.com/api/v1/users/<user_id>/disable

Scope - idmpod.user.ALL OR idmpod.user.WRITE OR idmpod.user.UPDATE

Response

Success

Response code - 204

Failure

Response code - <error-response-code>

{
	"error": {
	   "code": <error-code>,
	   "detail": <error-detail>,
	   "title": <error-title>
   }
}

Delete user

Use this API to delete a user.

Use this API to delete a user from its primary directory and Universal Directory:
DELETE https://id360.manageengine.com/api/v1/users/<user_id>

Scope - idmpod.user.ALL OR idmpod.user.WRITE OR idmpod.user.DELETE

Response

Success

Response code - 204

Failure

Response code - <error-response-code>

{
	"error": {
	   "code": <error-code>,
	   "detail": <error-detail>,
	   "title": <error-title>
   }
}

Create user

Use this API to create a user.

Use this API to create a user in Universal Directory with the given input only:
POST https://id360.manageengine.com/api/v1/users

Scope - idmpod.user.ALL OR idmpod.user.WRITE OR idmpod.user.CREATE

Request body

{
	"lastName": "Hales",
	"country": "US",
	"telephoneNumber": "9072746922",
	"zipPostal": "99501",
	"gender": "M",
	"city": "Anchorage",
	"mobileNumber": "7700900461",
	"displayName": "AlexHales",
	"employeeID": "12342",
	"language": "en",
	"title": "Manager",
	"workLocation": "Alaska",
	"postOfficeBox": "1052",
	"street": "19th Ave, Anchorage, Alaska",
	"seatingLocation": "5LC12",
	"company": "Berge Corporation",
	"fax": "441619998888",
	"email": "alexhales@company.com",
	"homePhone": "044-24681357",
	"stateProvince": "Alaska",
	"firstName": "Alex",
	"manager": "2000000072269",
	"password": "Test@1527#"
}

Response

Success

Response code - 201

{
	"data": {
		"lastName": "Hales",
		"country": "US",
		"telephoneNumber": "9072746922",
		"zipPostal": "99501",
		"gender": "M",
		"city": "Anchorage",
		"mobileNumber": "7700900461",
		"displayName": "AlexHales",
		"description": "User of marketing department",
		"employeeID": "12342",
		"language": "en",
		"title": "Manager",
		"manager": "2000000072269",
		"workLocation": "Alaska",
		"postOfficeBox": "1052",
		"street": "19th Ave, Anchorage, Alaska",
		"seatingLocation": "5LC12",
		"company": "Berge Corporation",
		"id": "2000000000001",
		"isDomainVerified": "false",
		"fax": "441619998888",
		"email": "alexhales@company.com",
		"homePhone": "044-24681357",
		"stateProvince": "Alaska",
		"firstName": "Alex",
		"status": 1,
		"primarySource": {
			"modifiedTime": "2023-12-12T14:32:50+05:30",
			"applicationService": {
				"name": "Universal Directory",
				"logo": "universal-directory",
				"id": "2000000018007",
				"serviceName": "ZOHO_DIRECTORY"
			},
			"creationTime": "2023-12-12T14:32:50+05:30",
			"isEnabled": true,
			"id": "2000000072637",
			"applicationName": "Berge-Corp"
		}
	}
}

Failure

Response code - <error-response-code>

{
	"error": {
	   "code": <error-code>,
	   "detail": <error-detail>,
	   "title": <error-title>
   }
}

Create user using template

Use this API to create a user using a given template.

Use this API to create a user in Universal Directory with the given template:
POST https://id360.manageengine.com/api/v1/users/new/<template_id>

Scope - idmpod.user.ALL OR idmpod.user.WRITE OR idmpod.user.CREATE

Note: For this API, the user's given value will be given higher priority over the value given in the template.

Request body

{
	"lastName": "Hales",
	"telephoneNumber": "9072746922",
	"zipPostal": "99501",
	"city": "Anchorage",
	"mobileNumber": "7700900461",
	"employeeID": "12342",
	"title": "Manager",
	"workLocation": "Chennai",
	"postOfficeBox": "1052",
	"street": "19th Ave, Anchorage, Alaska",
	"seatingLocation": "5LC12",
	"company": "Berge Corporation",
	"fax": "441619998888",
	"email": "alexhales@company.com",
	"homePhone": "044-24681357",
	"stateProvince": "Alaska",
	"firstName": "Alex",
	"password": "Test@1527#"
}

Response

Success

Response code - 201

{
	"data": {
		"lastName": "Hales",
		"country": "US",
		"telephoneNumber": "9072746922",
		"zipPostal": "99501",
		"gender": "M",
		"city": "Anchorage",
	   "mobileNumber": "7700900461",
		"displayName": "AlexHales",
		"description": "User of marketing department",
		"employeeID": "12342",
		"language": "en",
		"title": "Manager",
		"manager": "2000000072269",
		"workLocation": "Alaska",
		"postOfficeBox": "1052",
		"street": "19th Ave, Anchorage, Alaska",
		"seatingLocation": "5LC12",
		"company": "Berge Corporation",
		"id": "2000000000001",
	   "isDomainVerified": "false",
		"fax": "441619998888",
		"email": "alexhales@company.com",
		"homePhone": "044-24681357",
		"stateProvince": "Alaska" ,
		"firstName": "Alex",
		"status": 1,
		"primarySource": {
			"modifiedTime": "2023-12-12T14:32:50+05:30",
			"applicationService": {
				"name": "Universal Directory",
				"logo": "universal-directory",
				"id": "2000000018007",
				"serviceName": "ZOHO_DIRECTORY"
			},
			"creationTime": "2023-12-12T14:32:50+05:30",
			"isEnabled": true,
			"id": "2000000072637",
			"applicationName": "Berge-Corp"
		}
	}
}

Failure

Response code - <error-response-code>

{
	"error": {
	"code": ,
	"detail": ,
	"title": 
   }
}

Modify user

Use this API to modify user details. This API will modify only the provided attributes.

Use this API to modify a user in the Universal Directory:
PATCH https://id360.manageengine.com/api/v1/users/{user_id}

Scope - idmpod.user.ALL OR idmpod.user.WRITE OR idmpod.user.UPDATE

Request body

{
    "country": "CA",
    "language": "en-CA",
    "city" : "Ottawa"
    "stateProvince" : "Ontario",
    "zipPostal" : "K0A0A4",
    "street": "Colonel Murray St, Ottawa, Ontario",
    "displayName": "Hales",
    "manager": "2000000072271"
}

Response

For the API for modifying users, all the supported attributes will be returned.

Success

Response Code - 200

{
	"data": {
		"lastName": "Hales",
		"country": "CA",
		"telephoneNumber": "9072746922",
		"zipPostal": "K0A0A4",
		"gender": "M",
		"city": "Ottawa",
		"mobileNumber": "7700900461",
		"displayName": "Hales",
		"description": "User of marketing department",
		"employeeID": "12342",
		"language": "en-CA",
		"title": "Manager",
		"manager": "2000000072271",
		"workLocation": "Alaska",
		"postOfficeBox": "1052",
		"street": "Colonel Murray St, Ottawa, Ontario",
		"seatingLocation": "5LC12",
		"company": "Berge Corporation",
		"id": "2000000000001",
		"isDomainVerified": "false",
		"fax": "441619998888",
		"email": "alexhales@company.com",
		"homePhone": "044-24681357",
		"stateProvince": "Ontario",
		"firstName": "Alex",
		"status": 1,
		"primarySource": {
			"modifiedTime": "2023-12-12T14:32:50+05:30",
			"applicationService": {
				"name": "Universal Directory",
				"logo": "universal-directory",
				"id": "2000000018007",
				"serviceName": "ZOHO_DIRECTORY"
			},
			"creationTime": "2023-12-12T14:32:50+05:30",
			"isEnabled": true,
			"id": "2000000072637",
			"applicationName": "Berge-Corp"
		}
	}
}

Failure

Response code - <error-response-code>

{
	"error": {
	   "code": <error-code>,
	   "detail": <error-detail>,
	   "title": <error-title>
   }
}

User API errors

Error code Title Description
00010104 Invalid Attribute Found The provided select or sort attribute has invalid attribute(s).
00010105 User Not Found The specified user in the request was not found, or the user attempting to perform the action lacks the necessary permissions to do so.
00010106 Directory Not found The directory ID provided in the request is invalid or does not match any existing directories.
00010109 Unlicensed User The provided user ID is associated with an unlicensed user, and actions cannot be performed on users without a valid license.
00010110 Invalid Attribute Value The value provided for an attribute is invalid. For example, if the API expects the country to be in the ISO 3166-1 code format, but the user inputs India or an incorrect code, it is considered an invalid value for the country attribute.
00010111 Template Validation Failed This error occurs during template validation when creating a user. It indicates that there is an issue with the input.
00010112 Template Not Found The provided template ID is invalid or not applicable for the current directory. The template ID cannot be null—it must correspond to the directory where the action is being performed, and currently, only templates for Zoho are supported. Additionally, templates with multiple mandatory directories are not supported at this time.
00010113 Invalid Pagination Cursor The pagination cursor provided is invalid. It either has an incorrect format or does not align with the one generated by the system.
09000001 Invalid Input Data. The input data provided in the request is either missing, incomplete, or does not meet the required format.

Supported attributes

Attributes marked with * are mandatory for creation.

Attributes DataType Description
city String The city where the user is located.
company String The name of the company the user works for.
country String The country where the user resides, using ISO 3166-1 codes.
department String The department within the organization to which the user belongs.
description String Additional information or a summary about the user.
displayName * String The name displayed for the user in the system.
email * String The user’s email address.
employeeID String A unique ID assigned to the employee within the organization.
fax String The fax number associated with the user.
firstName * String The user's first name.
gender String The gender identity of the user.Use a single character: M (Male), F (Female), or N (Other).
homePhone String The user’s home phone number.
id (Read Only) String The unique identifier for the user, assigned by the system.
isDomainVerified (Read Only) Boolean Indicates if the user’s domain has been verified.
language String The user's preferred language for communication.Use an ISO 639-1 code, or a combination of ISO 639-1 and ISO 3166-1 (e.g., en, zh, ta, or en-US, zh-CN, ta-IN).
lastName String The user's last name.
manager String The user ID of the user’s direct manager.
mobileNumber String The user’s mobile phone number.
password * (Write Only) String The password for the user’s account.
postOfficeBox String The user's P.O. box address.
primarySource (Read Only) JsonObject Details about the user's primary directory.
    applicationService JsonObject Details about the service associated with the directory or app.
    applicationName String The name of the application or directory.
    creationTime String The timestamp when the template was created, in ISO 8601 format.
    id String The unique identifier for the directory.
    isEnabled Boolean Indicates whether the directory is enabled or disabled.
    modifiedTime String The timestamp for the most recent modification, in ISO 8601 format.
seatingLocation String The physical seating location of the user within the office or facility.
stateProvince String The state or province where the user resides.
status(Update Only) Integer The user’s current status: 1 for active, 0 for inactive.
street String The street address of the user.
telephoneNumber String The telephone number of the user.
title String The user's job title or role within the organization.
workLocation String The location where the user works.
zipPostal String The postal or ZIP code for the user's address.

Copyright © 2024, ZOHO Corp. All Rights Reserved.