Add a user

Add a new user to the organization and receive the user ID upon a successful API call.


Request URL


Choose domain-specific URL to replace {api-domain}

You can use the domain-specific URL to access Bigin resources. Based on the data center in which the Bigin account's resources are available, replace {api-domain} in the preceding request with one of the following API domain URLs:

  • For US,
  • For EU,
  • For AU,
  • For IN,
  • For CN,
  • For JP,

For more information, see Multi DC Support.



For this endpoint, pass the access token as an authorization header. See OAuth Authentication for more information about access tokens.

Authorization: Zoho-oauthtoken <ACCESS_TOKEN>

You must authenticate using an access token that is associated with one of the following scopes:

  • ZohoBigin.users.ALL
  • ZohoBigin.users.CREATE


  • Only one user can be added per request.
  • In the request body, use field API names. Retrieve the api_name value for each field from the Fields metadata API.

Request parameters

The available request parameters are given below:

Body parameters

last_name stringRequired

The last name of the user.

first_name stringRequired

The first name of the user.

email stringRequired

The email ID of the user.

role stringRequired

The ID of the role to which the user will be assigned. You can get the Role ID from the Get all roles data API.

profile stringRequired

The ID of the profile to which the user will be assigned. You can get the Profile ID from the Get all profiles data API.

Sample request

Copiedcurl "" \
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf" \
-d "@newuser.json"

Copiednew_user = Map();
new_user.put("last_name", "Boyle");
new_user.put("email", "");
new_user.put("role", "692969000000015969");
new_user.put("profile", "692969000000015972");

user_info = List();

params = Map();
params.put("user_info", user_info);

response = invokeurl
	url: ""
	type: POST
	parameters: params.toString()
info response ;

Sample request body

Copied//Consider the following data is saved in a file 'newuser.json'
    "users": [
            "first_name": "Patricia",
            "last_name": "Boyle",
            "email": "",
            "role": "692969000000015969",
            "profile": "692969000000015972"

Response object

The response object provides information regarding the success message or status.

Possible error codes

The response of this resource includes HTTP status and error codes.

The most common HTTP error codes that occur when you request access to this endpoint are given in the following:


    Request exceeds your license limit. Need to upgrade in order to add.
    Resolution: The maximum number of users you can add per your Bigin plan has exceeded. Please buy additional user licenses to add more users.


    Failed to add user since same email id is already present
    Resolution: The user you are trying to add already exists in your organization.


    Company Name is required
    Resolution: Company name is not specified in the request body.


    Invalid data.
    Resolution: Email Id should not contain Please choose a different email id (OR) Invalid Email Id. Please choose a different email id The email ID is either invalid or contains

Sample Response

    "users": [
            "code": "SUCCESS",
            "details": {
                "id": "2034020000000630024"
            "message": "User added",
            "status": "success"