Add User

Purpose

To add a user to your organization.

Request URL

https://www.zohoapis.com/crm/v2/users

Request Method

POST

Scope

scope=ZohoCRM.users.ALL
(or)
scope=ZohoCRM.users.CREATE

Possible operation types
ALL - Full access to data
CREATE - Create user data
Note:
  • You can add only one user per POST request.

  • Adding a CRM Plus user through API is not supported. You can only add a CRM Plus user through the UI.

  • You must use only Field API names in the input. You can obtain the field API names from Fields metadata API (the value for the key “api_name” for every field).

Request JSON

AttributeData TypeMandatoryDescription
last_nameStringYesLast name of the user.
emailemailYesThe Email ID of the user.
roleStringYesThe unique ID of the role you want to assign the user with. You can obtain the role ID from the Roles API.
profileStringYesThe unique ID of the profile you want to assign the user with, to decide the user's level of access to CRM data. You can obtain the profile ID from the Profiles API.

Apart from the above mentioned mandatory fields, you can use all system-defined and custom fields in the input.
The JSON type and the data type of the field-types are extracted from fields meta data API.
JSON type - Tells in what format the field should be passed in request-body or will be received in response.
Data type - Tells the type of data that can be stored in the corresponding field-type. It is mentioned below each Attribute.

 
AttributeJSON TypeLimitationsSample
Single Line
Text
StringAccepts up to 255 characters.
Accepts alphanumeric and special characters.
"Last_Name": "Mike O'Leary"
Multi Line
Textarea
StringSmall - accepts up to 2000 characters.
Large - accepts up to 32000 characters.
You will not be able to use this field to create custom views, reports or other filters.
Accepts alphanumeric and special characters.
"Multi_Line_1": "This is the first line \n Now for the second Line"
Email
Email
StringAccepts valid email IDs."Email_1": "p.boyle@zylker.com"
Phone
Phone
StringAccepts up to 30 characters. This limit may vary based on the value configured in 'Number of characters allowed' in the properties pop-up of the field, in UI.
Accepts only numeric characters and '+' (to add extensions).
The regex pattern in Zoho CRM to validate this field's value is "[0-9a-zA-Z!#;%\\*\\^\\(\\)=\\{\\}\\[\\]\\?`~_\\-\\.\\$@\\?\\,\\:\\'\\/\\!\\P{InBasicLatin}\\|\\\\\\s\\+]+"
"Phone_1": "9900000000"
Picklist
Picklist
StringYou can either pass an existing pick list value or add a new one.
The pick list value accepts all alphanumeric and special characters.
"Industry": "automobile"
Multi-Select Picklist
Multi-select Picklist
JSON arrayYou can either pass existing pick list values or add a new one.
The pick list value accepts all alphanumeric and special characters.
"Courses_Opted": [
"Analytics",
"Big data"
]
Date
Date in ISO 8601 format
StringAccepts date in yyyy-MM-dd format"Date_1": "2017-08-16"
Date/time
DateTime in ISO 8601 format
StringAccepts date and time in yyyy-MM-ddTHH:mm:ss±HH:mm ISO 8601 format"Date_Time": "2017-08-16T14:32:23+05:30"
Date_Time is in ISO8601 format and the time zone is the current user's time zone.
Number
Integer
IntegerAccepts numbers up to 9 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"No_of_Employees": 350
Currency
Currency
DoubleBefore decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"Annual_Revenue": 250000.90
Decimal
Double
DoubleBefore decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
After decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"Decimal_1": 250000.50
Percent
Double
DoubleAccepts numbers up to 5 digits.
Accepts only numeric values.
"Percentage": 25
Long Integer
BigInt
StringAccepts numbers up to 18 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI.
Accepts only numeric values.
"EAN_Code":"0012345600012"
Checkbox
Boolean
BooleanAccepts only Boolean values(true,false)."Email_Opt_Out": true
URL
Website
StringAccepts valid URLs.
The regex pattern in Zoho CRM to validate this field's value is "^(http:\\/\\/www.|https:\\/\\/www.|ftp:\\/\\/www.|www.|http:\\/\\/|https:\\/\\/|ftp:\\/\\/|).+$"
"URL": "https://www.zylker.com"
Lookup
Lookup
JSON objectAccepts valid name and unique ID of the record, which you can get through meta data API."Lookup" : {
"name" : "James",
"id" : "425248000000104001"
}
Multi-select lookup
Multi-Select Lookup
JSON arrayAccepts valid record names and unique IDs."Accounts":[
{
"Account_Name":"Zylker1",
"id":"4150868000000420069"
},
{
"Account_Name":"Zylker",
"id":"4150868000000420046"
}
]
User
User Lookup
JSON objectThis is a default look-up field to users in Zoho CRM."User":
{
"name":"Patricia Boyle",
"id":"4150868000000623001"
}

Possible Errors

HTTP StatusError CodeMessageReason
400invalid_requestCannot add user under CRM Plus account. Kindly use CRMPlus URL to add userAdding a CRM Plus user through API is not supported. You can only add a CRM Plus user through the UI.
400license_limit_exceededRequest exceeds your license limit. Need to upgrade in order to addThe maximum number of users you can add per your CRM plan has exceeded.
400duplicate_dataFailed to add user since same email id is already presentThe user you are trying to add already exists in your organization.
400invalid_dataEmail Id should not contain @skydesk.jp. Please choose a different email id (OR) Invalid Email Id. Please choose a different email idThe email ID is either invalid or contains @skydesk.jp.
400unapprovableCannot add user for CRMPlus account from CRM. Kindly add user through CRMPlusAdding a CRM Plus user through API is not supported. You can only add a CRM Plus user through the UI.
400mandatory_not_foundCompany Name is requiredCompany name is not specified in the request body.
400internal_errorError occurred in resending the invitation of CRMPLUS user in CRM accountYou can only re-invite a CRM Plus user from the CRM UI, not through API.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/users"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
Copiedimport java.util.List;

import com.zoho.crm.library.api.APIConstants;
import com.zoho.crm.library.api.response.APIResponse;
import com.zoho.crm.library.api.response.BulkAPIResponse;
import com.zoho.crm.library.common.ZCRMEntity;
import com.zoho.crm.library.crud.ZCRMOrgTax;
import com.zoho.crm.library.crud.ZCRMTax;
import com.zoho.crm.library.setup.metadata.ZCRMOrganization;
import com.zoho.crm.library.setup.restclient.ZCRMRestClient;
import com.zoho.crm.library.setup.users.ZCRMProfile;
import com.zoho.crm.library.setup.users.ZCRMRole;
import com.zoho.crm.library.setup.users.ZCRMUser;
import com.zoho.oauth.client.ZohoOAuthClient;
import com.zoho.oauth.contract.ZohoOAuthTokens;

public class Org{
	public Org() throws Exception{
		ZCRMRestClient.initialize();
	}
	public void addUser() throws Exception{
		ZCRMRestClient client = ZCRMRestClient.getInstance();
		ZCRMUser user=ZCRMUser.getInstance(null);//null is passed to the entity id
		user.setFirstName(“Patricia”);
		user.setFullName(“Patricia Boyle”);
		user.setLastName(“Boyle”);
		user.setEmailId(“Patricia@abc.com”);
		ZCRMRole role=ZCRMRole.getInstance(554023000000015969L, “Manager”);//554023000000015969L-entity id,"CEO" is the role name
		user.setRole(role);
		ZCRMProfile profile=ZCRMProfile.getInstance(554023000000015975L,”Standard”);//554023000000015975L-entity id,"Standard" -profile name
		user.setProfile(profile);
		ZCRMOrganization org=client.getOrganizationInstance();
		APIResponse response=org.addUser(user);
		System.out.println("HTTP status code"+response.getStatusCode());
		System.out.println("Status"+response.getStatus());
		System.out.println("message"+response.getMessage());
		System.out.println("details"+response.getResponseJSON());
	}
	public static void main(String[] args) throws Exception {
		Org obj=new Org();
		obj.addUser();
	}
}
Copied# Create user
# -----------
def create_user(self):
    try:
        user_ins = zcrmsdk.ZCRMUser.get_instance()
        user_ins.last_name = "Boyle"
        user_ins.email = 'Patricia@abc.com'
        user_ins.role = zcrmsdk.ZCRMRole.get_instance(554023000000015969, 'Manager')# role id and role name
        user_ins.profile = zcrmsdk.ZCRMProfile.get_instance(554023000000015975, 'Standard')# profile id and profile name
        resp = zcrmsdk.ZCRMOrganization.get_instance().create_user(user_ins)
        print(resp.status_code)
        print(resp.message)
        print(resp.code)
        print(resp.status)
        print(resp.details)
        print(resp.data)
    except zcrmsdk.ZCRMException as ex:
        print(ex.status_code)
        print(ex.error_message)
        print(ex.error_code)
        print(ex.error_details)
        print(ex.error_content)
 
Copied<?php
use zcrmsdk\crm\setup\restclient\ZCRMRestClient;
use zcrmsdk\crm\setup\users\ZCRMProfile;
use zcrmsdk\crm\setup\users\ZCRMRole;
use zcrmsdk\crm\setup\users\ZCRMUser;
require 'vendor/autoload.php';
class Org{
    public function __construct()
    {
            $configuration = array("client_id"=>{client_id},"client_secret"=>{client_secret},"redirect_uri"=>{redirect_url},"currentUserEmail"=>{user_email_id});
            ZCRMRestClient::initialize($configuration);
    }
    public function createUser(){
        $orgIns = ZCRMRestClient::getOrganizationInstance(); // to get the organization instance
       
        $user=ZCRMUser::getInstance(NULL, NULL);//to get the user instance
        $user->setLastName("Boyle");//to set the last name of the user
        $user->setFirstName("Patricia");//to set the first name of the user
        $user->setEmail("Patricia@abc.com");//to set the email id of the user
        $role=ZCRMRole::getInstance("554023000000015969","Manager");//to get the role
        $user->setRole($role);//to get the role of the user
        $profile=ZCRMProfile::getInstance("554023000000015975","Standard");//to get the profile
        $user->setProfile($profile);//to set the profile of the user
        $responseIns=$orgIns->createUser($user);//to create the user
        echo "HTTP Status Code:".$responseIns->getHttpStatusCode(); //To get http response code
        echo "Status:".$responseIns->getStatus(); //To get response status
        echo "Message:".$responseIns->getMessage(); //To get response message
        echo "Code:".$responseIns->getCode(); //To get status code
        echo "Details:".json_encode($responseIns->getDetails());
    }
}
    $obj =new Org();
    $obj->createUser();
 
Copied/** To create new user */
public void CreateUser()
{
    ZCRMUser user = ZCRMUser.GetInstance("Boyle", "Patricia@abc.com"); //last_name and email of the user
    ZCRMOrganization OrgInstance = ZCRMRestClient.GetInstance().GetOrganizationInstance();
    user.Country = "US";
    user.Role = ZCRMRole.GetInstance(554023000000015969, "Manager");
    user.CountryLocale = "en_US";
    user.FirstName = "Patricia";
    user.Profile = ZCRMProfile.GetInstance(554023000000015975, "Standard");
    user.DateOfBirth = "1990-12-31";
    user.DateFormat = "MM/dd/yyyy";

    user.SetFieldValue("FieldApiName","FieldValue");
    APIResponse response = OrgInstance.CreateUser(user);
    Console.WriteLine(response.HttpStatusCode);
    Console.WriteLine(response.Status);
    Console.WriteLine(response.ResponseJSON);
    Console.WriteLine(response.Message);
    Console.WriteLine(JsonConvert.SerializeObject(response));
    Console.WriteLine("\n\n\n");
}
 

Sample Response

Copied{
  "users": [
    {
      "role": "554023000000015969",
      "first_name": "Patricia",
      "email": "Patricia@abcl.com",
      "profile": "554023000000015975",
      "last_name": "Boyle"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}

Sample Response

Copied{
  "users": [
    {
      "role": "554023000000015969",
      "first_name": "Patricia",
      "email": "Patricia@abcl.com",
      "profile": "554023000000015975",
      "last_name": "Boyle"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}

Sample Response

Copied{
  "users": [
    {
      "role": "554023000000015969",
      "first_name": "Patricia",
      "email": "Patricia@abcl.com",
      "profile": "554023000000015975",
      "last_name": "Boyle"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}

Sample Response

Copied{
  "users": [
    {
      "role": "554023000000015969",
      "first_name": "Patricia",
      "email": "Patricia@abcl.com",
      "profile": "554023000000015975",
      "last_name": "Boyle"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}
Copied{
  "users": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "554023000000691003"
      },
      "message": "User added",
      "status": "success"
    }
  ]
}