Get Users

Overview
Syntax
Scope
Example 1
Example 2
Response Format

Overview

The zoho.directory.getUsers task is used to fetch all the users within an organization.

Syntax

<response> = zoho.directory.getUsers(<orgID>, <page>, <perPage>, <queryParams>, <connectionName>);

Scope

ZohoDirectory.Users.READ

Where:

Parameter	Description	Data type
response	is the variable that will hold the details of the users fetched from the organization.	KEY-VALUE
<orgID>	is the ID of the organization from which the users need to be fetched.	NUMBER
<queryParams>	is the variable that holds the query parameters, Filters Include	KEY-VALUE
<connectionName>	is the name of the Zoho Directory connection.	TEXT
<page>	To get the list of records based on pages.	NUMBER
<per_page>	Maximum number of records (1–200) in a single page.	NUMBER

The below-mentioned parameters can be used in <queryParams>:

Supported Filters:

Parameters	Description
filter_user_state	User states like not joined and not invited can be filtered using this filter. Know more. Example: To get a list of users who haven't joined the organization yet, use ("filter_user_state", "not_joined") in your script. Allowed values: not_invited not_joined
filter_status	User statuses like inactive can be used to get inactive users in an organization. Know more. Allowed values: active inactive
filter_user_type	User types like confirmed and external can be used to filter users in an organization. Know more. Allowed values: confirmed pending external

Supported Includes:

Parameters	Description
address	Including address in the fetch call will return the user's full address along with other details in the response.
custom_fields	Used to retrieve custom field data as part of the user's details.
user.location	Used to fetch user's location details in the response.
emails	Including emails will provide information, such as primary and secondary email addresses of the user.
user.extendedinfo	Use extendedinfo to fetch additional information of the user like date of birth, designation, and date of joining.
user.departmentinfo	Include departmentinfo to retrieve department details as part of the user's information.

Example 1: Fetch 200 users from the specified organization

The following script fetches the first 200 users from a Zoho Directory organization:

response = zoho.directory.getUsers(72XXXXXXX, "1", "200", Map(), "zoho_directory_connection");

where:

response

This is the KEY-VALUEresponse returned by Zoho Directory.

"72XXXXXXX"

This is the NUMBER is the NUMBER that represents the organization ID of Zoho Directory account from which the users need to be fetched.

zoho_directory_connection

This is theTEXT that represents the link name of the connection.

This is theNUMBER that represents the index number of the first record that needs to be fetched.

This is theNUMBER that represents the total number of records that needs to be fetched.

Example 2: Fetch the first 200 confirmed users from the specified organization with the use of filters

The following script fetches the first 200 confirmed users from Zoho Directory organization with the use of filters, and that includes:

queryParams = Map();
filters = Map();
include = [];
include.add("address");
include.add("custom_fields");
include.add("emails");
include.add("user.location");
include.add("user.extendedinfo");
filters.put("filter_user_type","confirmed");
queryParams.put("include", include);
queryParams.put("filters", filters);
response = zoho.directory.getUsers(72XXXXXXX, "1", "200", queryParams, "zoho_directory_connection")

where:

address, custom_fields, emails, user.location, and user.extendedinfo.

is the additional information included to fetch along with users. The mentioned parameters are the supported filters.

confirmed

is the user filter type that needs to be fetched. Other supported filters are: filter_status and filter_user_state.

Response Format

{
"status_code": 200,
    "users": [{
        "address": [
            {
                "address_type": 1,
                "city": “****”,
                "country": “**”,
                "country_display_name": “*****”,
                "extension": “2***”,
                "mobile": “99*******”,
                "phone": “89*******”,
                "postal_code": “66*****”,
                "seating_location": “O****”,
                "state": “******”,
                "street_address": “***”
            }
        ],
        "country_code": "gb",
        "customFields": [
            {
                "field_id": "79***********",
                "field_name": "BLOOD-GROUP",
                "field_value": “**”
            },
            {
                "field_id": "79***********",
                "field_name": "Height",
                "field_value": ***
            }
        ],
        "designation_id": "71******”,
        "display_name": “ki******”,
        "emails": [
            {
                "email_id": “ki******@*******.***”,
                "is_primary": true,
                "is_verified": true
            }
        ],
        "employee_id": “3****”,
        "first_name": “Ki******",
        "full_name": "ki******",
        "gender": "M",
        "is_active": true,
        "is_admin": false,
        "is_confirmed": true,
        "is_invited": false,
        "is_joined": false,
        "language_code": "en-us",
        "last_name": "",
        "reportingTo": {
            "emails": [
                {
                    "email_id": "na******@*******.***",
                    "is_primary": true,
                    "is_verified": true
                }
            ],
            "user_id": "79***********",
            "zuid": "77*******"
        },
        "timezone": "Asia/Kolkata",
        "user_id": "79**************”,
        "user_type": "confirmed",
        "zuid": "77*******"
},...]
    "resource_name": "users"
}