Users APIs

In Zoho Directory, you can add users such as employees or external users to your organization. The Users API allows you to add users, deactivate users, activate users, update their details, and more.

End Points

POST

/orgs/{org_id}/users

GET

/orgs/{org_id}/users

PUT

/orgs/{org_id}/users/{user_id}

GET

/orgs/{org_id}/users/{user_id}

Create a user

Creates a user in the mentioned organization.
OAuth Scope : ZohoDirectory.Users.CREATE

Arguments

first_name

string

First name of the user.

last_name

string

Last name of the user.

emails

array

Lists the email addresses associated with the user along with its details.

Show Sub-Attributes

email_id

string

(Required)

Specify the user email id

department_id

string

ID of the department to which the user is assigned.

designation_id

string

ID of the designation to which the user is assigned.

work_location

string

Work location of the user.

date_of_birth

date-time

Date of birth of the user.

date_of_joining

date-time

Date when the user joined the company.

gender

string

Gender of the user. M indicates Male, F indicates Female and N indicates not prefers to say.

employee_id

string

Employee ID of the user.

reporting_to

Details about the user to whom the corresponding user is reporting.

address

array

Address of the user will be mentioned in this array.

Show Sub-Attributes

seating_location

string

Specify the seating location information

timezone

string

Timezone added under the locale information in the user's profile.

language_code

string

Code of the language mentioned in the user profile.

country_code

string

Code of the country mentioned in the user profile.

notify_mail

boolean

If true, an invitation mail will be sent to the user based on the successful user addition

customFields

array

Lists the custom fields available for the user and its values.

Show Sub-Attributes

field_id

string

Specify the custom field id

field_value

string

Specify the custom field value

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

Request Example

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/users")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/users"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/directory/api/v2/orgs/987000000654321/users",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/directory/api/v2/orgs/987000000654321/users", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request POST \
  --url https://zohoapis.com/directory/api/v2/orgs/987000000654321/users \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "users": {
        "first_name": "James",
        "last_name": "Walker",
        "emails": [
            {
                "email_id": "haxxxxxxxxxxxxxxxxx.com"
            }
        ],
        "department_id": "1xxxxxxx6",
        "designation_id": "9xxxxxx4",
        "work_location": "Work Location 1",
        "date_of_birth": "1990-12-25T12:55:58.962+0530",
        "date_of_joining": "2022-12-25T12:55:58.962+0530",
        "gender": "M",
        "employee_id": "1003",
        "reporting_to": "2xxxxxxxxxxxxxxxx6",
        "address": [
            {
                "seating_location": "Sample Value"
            }
        ],
        "timezone": "Etc/GMT+12",
        "language_code": "en",
        "country_code": "in",
        "notify_mail": true,
        "customFields": [
            {
                "field_id": "2xxxxxxxxxxxxxxxx3",
                "field_value": "Sample Value"
            }
        ]
    }
}

Response Example

{
    "status_code": 201,
    "resource_name": "users",
    "message": "... //Successfully completed",
    "users": {
        "user_id": ".....",
        "href": "....."
    }
}

{
    "status_code": 400,
    "error_code": "invite_user",
    "message": "If the primary email domain is not mail-hosted or verified, user must be invited instead"
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "If the current user does not have the required permission"
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}

{
    "status_code": 405,
    "error_code": "subscription_expired",
    "message": "If the paid plan expired"
}

{
    "status_code": 409,
    "error_code": "resource_already_exists",
    "message": "If the given email address already exists"
}

{
    "status_code": 500,
    "error_code": "domain_mapped_with_another_deployment",
    "message": "If the given email id is registered in another the DC"
}

Get all users in an organization

Fetches all the users available in the organization along with their profile information.
OAuth Scope : ZohoDirectory.Users.READ

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

Query Parameters

page

integer

Represents the page number from which the records were fetched. The default value is 1

per_page

integer

Represents the number of records you can fetch in a single API call. The maximum value is 500

include

string

includes mentioned resource(s) info in the response
Allowed values:
user.departmentinfo: Adds assigned department details
user.extendedinfo: Adds extendedinfo such as employee_id, designation_id and reporting_to user details
custom_fields: To include custom fields details
address: To include address details
user.location: To include the user location details
emails: To include the user emails info

filter_email

string

Email Id of the user to filter by

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/users")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/users"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/directory/api/v2/orgs/987000000654321/users",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/directory/api/v2/orgs/987000000654321/users", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request GET \
  --url https://zohoapis.com/directory/api/v2/orgs/987000000654321/users \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

Response Example

{
    "status_code": 200,
    "resource_name": "users",
    "users": [
        {
            "user_id": "2xxxxxxxxxxxxxxxx6",
            "primary_email": "haxxxxxxxxxxxxxxxxx.com",
            "first_name": "James",
            "last_name": "Walker",
            "full_name": "James Walker",
            "display_name": "Zylker",
            "gender": "M",
            "date_of_birth": "1990-12-25T12:55:58.962+0530",
            "date_of_joining": "2022-12-25T12:55:58.962+0530",
            "language_code": "en",
            "country_code": "in",
            "timezone": "Etc/GMT+12",
            "employee_id": "1003",
            "user_status": 1,
            "user_role": 1,
            "user_type": "confirmed",
            "is_invited": true,
            "is_joined": true,
            "is_light_user": true,
            "designation_id": "9xxxxxx4",
            "department_id": "1xxxxxxx6",
            "work_location": "Work Location 1",
            "email_id": "haxxxxxxxxxxxxxxxxx.com",
            "customFields": [
                {
                    "field_id": "2xxxxxxxxxxxxxxxx3",
                    "field_name": "temporary",
                    "field_type": "String",
                    "field_value": "Sample Value",
                    "is_mandatory": true
                }
            ],
            "reporting_to": {
                "user_status": 1,
                "user_id": "2xxxxxxxxxxxxxxxx6",
                "first_name": "James",
                "last_name": "Walker",
                "display_name": "Zylker",
                "primary_email": "haxxxxxxxxxxxxxxxxx.com"
            },
            "emails": [
                {
                    "email_id": "haxxxxxxxxxxxxxxxxx.com",
                    "is_primary": true,
                    "is_verified": true
                }
            ],
            "created_time": "2024-xx-14T14:57:42.617+0530",
            "modified_time": "2025-01-22T15:41:32.487+0530",
            "address": [
                {
                    "street_address": "1xx, Dxxxxx xxxxx, xxxxxt",
                    "country": "in",
                    "country_display_name": "Sample Value",
                    "extension": "Sample Value",
                    "seating_location": "Sample Value",
                    "phone": "Sample Value",
                    "city": "Txxxxr",
                    "mobile": "Sample Value",
                    "state": "Kxxxxa",
                    "postal_code": "9xxxx9"
                }
            ],
            "created_by": {
                "user_id": "2xxxxxxxxxxxxxxxx6",
                "first_name": "James",
                "last_name": "Walker",
                "display_name": "Zylker"
            },
            "modified_by": {
                "user_id": "2xxxxxxxxxxxxxxxx6",
                "first_name": "James",
                "last_name": "Walker",
                "display_name": "Zylker"
            }
        },
        {...},
        {...}
    ]
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "ACCESS_DENIED",
    "message": "You do not have permission to perform this action."
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}

{
    "status_code": 405,
    "error_code": "unsupported_operation",
    "message": "If external-users-only filter is used on unsupported account type"
}

{
    "status_code": 422,
    "error_code": "unprocessable_api_request",
    "message": "If the API request contains invalid or unprocessable parameters"
}

Update a user's details

Updates a user's existing profile information with the provided information.
OAuth Scope : ZohoDirectory.Users.UPDATE

Arguments

address

array

Address of the user will be mentioned in this array.

Show Sub-Attributes

seating_location

string

Specify the seating location information

customFields

array

Lists the custom fields available for the user and its values.

Show Sub-Attributes

field_id

string

Specify the custom field id

field_value

string

Specify the custom field value

date_of_birth

date-time

Date of birth of the user.

date_of_joining

date-time

Date when the user joined the company.

department_id

string

ID of the department to which the user is assigned.

designation_id

string

ID of the designation to which the user is assigned.

employee_id

string

Employee ID of the user.

first_name

string

First name of the user.

last_name

string

Last name of the user.

gender

string

Gender of the user. M indicates Male, F indicates Female and N indicates not prefers to say.

language_code

string

Code of the language mentioned in the user profile.

reporting_to

Details about the user to whom the corresponding user is reporting.

timezone

string

Timezone added under the locale information in the user's profile.

country_code

string

Code of the country mentioned in the user profile.

work_location

string

Work location of the user.

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

user_id

string

(Required)

ID of the user.

Request Example

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6")
  .put(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("PUT", "/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request PUT \
  --url https://zohoapis.com/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "users": {
        "address": [
            {
                "seating_location": "Sample Value"
            }
        ],
        "customFields": [
            {
                "field_id": "2xxxxxxxxxxxxxxxx3",
                "field_value": "Sample Value"
            }
        ],
        "date_of_birth": "1990-12-25T12:55:58.962+0530",
        "date_of_joining": "2022-12-25T12:55:58.962+0530",
        "department_id": "1xxxxxxx6",
        "designation_id": "9xxxxxx4",
        "employee_id": "1003",
        "first_name": "James",
        "last_name": "Walker",
        "gender": "M",
        "language_code": "en",
        "reporting_to": "2xxxxxxxxxxxxxxxx6",
        "timezone": "Etc/GMT+12",
        "country_code": "in",
        "work_location": "Work Location 1"
    }
}

Response Example

{
    "status_code": 200,
    "resource_name": "users",
    "message": "... //Successfully completed",
    "users": {
        "user_id": ".....",
        "href": "....."
    }
}

{
    "status_code": 400,
    "error_code": "invalid_field_value",
    "message": "If invalid mobile number given"
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "no_permission",
    "message": "If the user does not have permission"
}

{
    "status_code": 404,
    "error_code": "resource_not_found",
    "message": "If no department for the given zgid"
}

{
    "status_code": 405,
    "error_code": "unsupported_operation",
    "message": "If the zgid is given as -1"
}

{
    "status_code": 409,
    "error_code": "resource_already_exists",
    "message": "If given employee is already associated for another user"
}

Get specific user details

Fetches specific user's profile information.
OAuth Scope : ZohoDirectory.Users.READ

Path Parameters

org_id

string

(Required)

The unique identifier of the org.

user_id

string

(Required)

ID of the user.

Query Parameters

include

string

Request Example

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://zohoapis.com/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://zohoapis.com/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "zohoapis.com",
  "port": null,
  "path": "/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

import http.client

conn = http.client.HTTPSConnection("zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

curl --request GET \
  --url https://zohoapis.com/directory/api/v2/orgs/987000000654321/users/2xxxxxxxxxxxxxxxx6 \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "status_code": 200,
    "resource_name": "users",
    "users": {
        "user_id": "2xxxxxxxxxxxxxxxx6",
        "primary_email": "haxxxxxxxxxxxxxxxxx.com",
        "first_name": "James",
        "last_name": "Walker",
        "full_name": "James Walker",
        "display_name": "Zylker",
        "gender": "M",
        "date_of_birth": "1990-12-25T12:55:58.962+0530",
        "date_of_joining": "2022-12-25T12:55:58.962+0530",
        "language_code": "en",
        "country_code": "in",
        "timezone": "Etc/GMT+12",
        "employee_id": "1003",
        "user_status": 1,
        "user_role": 1,
        "user_type": "confirmed",
        "is_invited": true,
        "is_joined": true,
        "is_light_user": true,
        "designation_id": "9xxxxxx4",
        "department_id": "1xxxxxxx6",
        "work_location": "Work Location 1",
        "email_id": "haxxxxxxxxxxxxxxxxx.com",
        "customFields": [
            {
                "field_id": "2xxxxxxxxxxxxxxxx3",
                "field_name": "temporary",
                "field_type": "String",
                "field_value": "Sample Value",
                "is_mandatory": true
            }
        ],
        "reporting_to": {
            "user_status": 1,
            "user_id": "2xxxxxxxxxxxxxxxx6",
            "first_name": "James",
            "last_name": "Walker",
            "display_name": "Zylker",
            "primary_email": "haxxxxxxxxxxxxxxxxx.com"
        },
        "emails": [
            {
                "email_id": "haxxxxxxxxxxxxxxxxx.com",
                "is_primary": true,
                "is_verified": true
            }
        ],
        "created_time": "2024-xx-14T14:57:42.617+0530",
        "modified_time": "2025-01-22T15:41:32.487+0530",
        "address": [
            {
                "street_address": "1xx, Dxxxxx xxxxx, xxxxxt",
                "country": "in",
                "country_display_name": "Sample Value",
                "extension": "Sample Value",
                "seating_location": "Sample Value",
                "phone": "Sample Value",
                "city": "Txxxxr",
                "mobile": "Sample Value",
                "state": "Kxxxxa",
                "postal_code": "9xxxx9"
            }
        ],
        "created_by": {
            "user_id": "2xxxxxxxxxxxxxxxx6",
            "first_name": "James",
            "last_name": "Walker",
            "display_name": "Zylker"
        },
        "modified_by": {
            "user_id": "2xxxxxxxxxxxxxxxx6",
            "first_name": "James",
            "last_name": "Walker",
            "display_name": "Zylker"
        }
    }
}

{
    "status_code": 401,
    "error_code": "INVALID_TOKEN",
    "message": "Authentication required."
}

{
    "status_code": 403,
    "error_code": "ACCESS_DENIED",
    "message": "You do not have permission to perform this action."
}

{
    "status_code": 404,
    "error_code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found."
}