Kaizen #51 - Handling Users with ZohoCRM API

Hello everyone!

Welcome back to yet another post in the Kaizen series.

This week, we will discuss the Zoho CRM Users API in detail.

Users in Zoho CRM

A user is the one who is allowed to access and manage the CRM records. Generally, anyone using CRM is a user. Further you can assign profiles and categorize the users based on their roles and permissions.

There are 4 major operations in Users API:

1. Get User(s) Data

2. Add User

3. Update User

4. Delete User

Note:

1. The oauth scopes required for all the mentioned Users API:

ZohoCRM.users.all

(or)

ZohoCRM.users.{operation_type}

2. The possible operation types are:

a. READ - Get User Data

b. CREATE - Create User Data

c. UPDATE - Update User Data

d. DELETE - Delete User Data

1. Get User(s) Data

To fetch the users data specified in the API request. The data to be fetched can be trimmed based on the user categories like AllUsers, ActiveUsers etc.

Request Method: GET

Request URL:

a. To fetch multiple users:

{{api-domain}}/crm/v2/users

b. To fetch a specific user:

{{api-domain}}/crm/v2/users/{user_id}

a. Sample Request:

{{api-domain}}/crm/v2/users?type=AllUsers

Let us see the parameters applicable to this API and their possible values:

Parameter Name	Data Type	Description and Possible Values
type	String	Specify the type of users to fetch.
page	Integer	Specify the list of user records as per their position in Zoho CRM. Default value is 1.
per_page	Integer	Specify the number of user records to be retrieved per page. Default value is 200.

Let us see the possible type of users in an organization:

User Type	Description
AllUsers	To list all the users in your organization (both active and inactive users). This is the default user type.
ActiveUsers	To get the list of all Active Users
DeactiveUsers	To get the list of all users who were deactivated
ConfirmedUsers	To get the list of all the confirmed users
NotConfirmedUsers	To get the list of all the non-confirmed users
DeletedUsers	To get the list of all the deleted users
ActiveConfirmedUsers	To get the list of all the active and confirmed users
AdminUsers	To get the list of all the admin users
ActiveConfirmedAdmins	To get the list of active users with the administrative privileges and are also confirmed
CurrentUser	To get the current CRM user

Sample Response:

b. Sample Request to fetch a specific user:

{{api-domain}}/crm/v2/users/3719520000000191015

Sample Response:

2. Add Users

To add an user to the organization.

Note: You can add only one user per request and you require to add Field API names in input. It can be fetched from Fields Meta Data API

Request Method: POST

Request URL:

{{api-domain}}/crm/v2/users

Mandatory keys in Request JSON

Key	Data type	Description
last_name	String	The last name of the user.
email	Email	The Email ID of the user
profile	String	The unique ID of the role to assign the user with. It can be obtained from the Roles API.
role	String	The unique ID of the profile to assign the user with. It can be obtained from the Profiles API.

Other than the mentioned mandatory keys, the input Json can contain the system-defined fields and custom fields such as Single Line, Currency, URL and Checkbox.

Sample Request JSON:

{

"users": [

{

"role": "3719520000000026005",

"city": "Chennai",

"state": "Tamil Nadu",

"first_name": "John",

"email": "john.mclane@zohocorp.com",

"website": "www.zoho.com",

"profile": "3719520000000026011",

"last_name": "Mclane"

}

]

}

Sample Response:

3. Update User

To update the details of a user of your organization. You will require to mention the user_id. The user_id can be obtained from Get Users API.

Request Method: PUT

Request URL:

If you intend to provide the user_id in the body as Json.

{{api-domain}}/crm/v2/users

If you intend to provide the user_id in the request URL.

{{api-domain}}/crm/v2/users/{user_id}

Note:

a. A deactivated user cannot be updated.

b. To activate/deactivate a user, use 'status' key in the input with the specified operation (active for activating and inactive for deactivating) as the value.

b. The time zone for another user cannot be updated, you can update your own time zone

Sample Request JSON:

You can update only one user per request. I am updating the city of the user that we added in Add User Operation.

{

"users": [

{

"city": "Banglore"

}

]

}

Sample Response:

4. Delete User

To delete a user from the organisation. You will require to mention the user_id. The user_id can be obtained from Get Users API.

Request Method: DELETE

Request URL:

If you intend to provide the user_id in the body as Json.

{{api-domain}}/crm/v2/users

If you intend to provide the user_id in the request URL.

{{api-domain}}/crm/v2/users/{user_id}

Sample Request:

{{api-domain}}/crm/v2/users/3719520000001093002

Sample Response:

Note:

a. By providing the type as 'DeletedUsers' in Get Users API, the deleted records can be fetched.

b. Deletion of primary contact is denied. To delete the primary contact, you will need to assign another contact as new primary contact.

Some common errors pertaining to Users API and ways to handle them:

HTTP Status Code	Error Code	Message	Reason/Handling
200	INVALID_DATA	The ID given seems to be invalid	You might have provided the incorrect ID in the request. Kindly provide the appropriate ID. The ID of a user can be obtained from Get Users API.
400	DUPLICATE_DATA	Failed to add user as the email id is already present.	The user already exists in the organisation
400	MANDATORY_NOT_FOUND	One of the mandatory key is missing.	Check if you have provided all the mandatory keys in the request.
400	LICENSE_LIMIT_EXCEEDED	Request exceeds your license limit. Need to upgrade in order to add	The maximum number of users you can add per your CRM plan has exceeded.
400	INVALID_REQUEST	Primary contact cannot be deleted.	You cannot delete the primary contact of your organization.
400	ID_ALREADY_DELETED	User is already deleted.	The user you want to delete is already deleted.
403	INACTIVE_USER	Inactive user cannot access the API.	Activate the user and then perform the desired operation.

These are the 4 major operations in Users API. Zoho CRM currently doesn't avail Search User API. It is currently in the development stage and it will be released soon.

We hope you found this post useful. Let us know your thoughts in the comment section or reach us out at support@zohocrm.com.

Cheers!

Access your files securely from anywhere

Zoho Developer Community

New to Zoho LandingPage?

Access Zoho LandingPage

Zoho LandingPage Resources

New to Zoho Survey?

Access Zoho Survey

Latest Feature Updates

Explore our Pricing & Plans

Zoho Survey Resources

Android Mobile Surveys

Insurvey Blogs

Insight Blogs

Tips & Tricks

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho CRM Plus?

Deliver unforgettable customer experiences

ACCESS ZOHO CRM PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Zoho Marketing Plus?

Everything you need to run your marketing

ACCESS ZOHO MARKETING PLUS

New to Bigin?

Signup Now

Access Bigin

Latest Feature Updates

Zoho Desk Resources

Desk Community Learning Series
Digest
Functions
Meetups
Kbase
Resources
Glossary
Desk Marketplace
MVP Corner
Word of the Day

Tout forum

France ZUGs

Zoho SalesIQ Resources

Topic Participants
Srivathsan N V

Sticky Posts
Kaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provide
Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Extension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use API
Kaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achieved
Extension pointers for integrating Zoho CRM with Zoho products #8: Upload and manage Zoho Workdrive folders and files from within Zoho CRM
Keeping records on your customers and business prospects is essential for tracking data, conducting follow-ups, and running a business smoothly. When you use two separate applications, and store relevant data in each, checking and tracking data becomes