Search Unassigned Users

Purpose

This API helps you to search users who are not assigned any threshold in the specified module.

Endpoints

GET /settings/automation/assignment_thresholds/actions/unassigned_users_search

Request Details

Request URL

{api-domain}/crm/{version}/settings/automation/assignment_thresholds/actions/unassigned_users_search

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.assignment_thresholds.{operation_type}

Possible Operation Types

ALL - Full access to Assignment Threshold data
READ - Fetch unassigned users for Assignment Threshold

Parameters

modulestring, mandatory
Specify the module for which you want to search the users without assignment threshold. Use the GET Modules Metadata API to retrieve the module API names.
Supported Modules: Leads, Contacts, Accounts, Deals, Cases and custom modules.
criteriastring, mandatory
- Specify the criteria in this format ({api_name}:{operator}:{value}) to search for unassigned users based on specific conditions.
  - (({field_API_name}:{operator}:{value}) {group_operator} ({field_API_name}:{operator}:{value}))
  - Replace {field_API_name}, {operator}, and {value} with the appropriate field API name, condition, and value.
- Supported fields: First Name, Last Name, Full Name and Email of the users.
- Supported operators: starts_with
- Supported group operators: and, or
- When using parentheses (()), commas (,), or a backslash (\) as the last character in a search value, follow these steps:
  1. Escape special characters using a backslash (\).
  2. Encode the value before making the API request. Select the value of the criteria, right-click the value, and choose the EncodeURIComponent option.
    Example 1 : Escaping Parentheses and Commas
    Search term: ((Last_Name:starts_with:Burns,B) and (First_Name:starts_with:M))
    1. Escape the comma (\,): ((Last_Name:starts_with:Burns\,B) and (First_Name:starts_with:M))
    2. Encode the value:((Last_Name:starts_with:Burns%5C%2CB) and (First_Name:starts_with:M))
    Example 2 : Escaping a Backslash at the End
    Search term: (Last_Name:starts_with:K\)
    1. Escape the backslash (\\): (Last_Name:starts_with:K\\)
    2. Encode the value: (Last_Name:starts_with:K%5C%5C)
typestring, optional
Use this parameter to specify the category of users to retrieve from Zoho CRM.
Below are the possible values:
- AllUsers: Retrieves all users (both active and inactive).
- ActiveUsers: Retrieves only active users.
- DeactiveUsers: Retrieves users who have been deactivated.
- ConfirmedUsers: Retrieves users who have confirmed their accounts.
- DeletedUsers: Retrieves users who have been deleted.
- ActiveConfirmedUsers: Retrieves users who are both active and confirmed.
- AdminUsers: Retrieves users with Administrator privileges.
- ActiveConfirmedAdmins: Retrieves active and confirmed administrators.
- CurrentUser: Retrieves the currently logged-in CRM user.
temp_idsstring, optional
Specify the temporary IDs of the users who are assigned a threshold but need to be included in the API response. You can provide multiple IDs separated by commas.
This parameter is mainly used in the create or update UI page of assignment threshold to include users added to a threshold but not yet saved, so they appear in the API response.
pageinteger, optional
To get the list of user records from the respective pages. Default value is 1.
per_pageinteger, optional
To set the number of user records to be retrieved per page. The default and the maximum possible value is 200.

Note

Use the page and per_page parameters to fetch unassigned user records in batches. Since a maximum of 200 records can be retrieved per API call, use multiple pages to fetch records more than 200. For example, page 1 and 2 with per_page=200 to fetch 400 records.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/assignment_thresholds/actions/unassigned_users_search?module=Leads&criteria=(first_name:starts_with:pat)&type=ActiveUsers"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response JSON

The users array is the root key that contains the list of users with no assignment threshold based on the request parameters. Each object in the array represents a user record and contains the following keys:
countrystring
Represents the country from the user's address.
citystring
Represents the city from the user's address.
streetstring
Represents the street from the user's address.
statestring
Represents the state from the user's address.
zipstring
Represents the ZIP code from the user's address.
country_localestring
Represents the locale of the user's country. For instance, 'en_IN'.
roleJSON object
Represents the name and ID of the role of the user.
Modified_ByJSON object
Represents the name and ID of the user who last modified the user's details.
Currencystring
Represents the user's currency preference.
aliasstring
Represents the alias name of the user.
idstring
Represents the unique ID of the user.
faxstring
Represents the fax number of the user.
emailstring
Represents the email address of the user.
mobilestring
Represents the mobile number of the user.
phonestring
Represents the phone number of the user.
first_namestring
Represents the first name of the user.
reporting_toJSON object
Represents the name and ID of the user to whom the user reports.
created_timestring
Represents the date and time at which the user was created.
websitestring
Represents the user's website details.
Modified_Timestring
Represents the date and time at which the user's details were last modified.
profileJSON object
Represents the name and ID of the profile of the user.
last_namestring
Represents the last name of the user.
time_zonestring
Represents the respective user's timezone.
created_byJSON object
Represents the name and ID of the user who created the user.
zuidstring
Represents the ZUID of the respective user.
confirmBoolean
Represents if the user is a confirmed user.
Possible values:
- true: The user is a confirmed user.
- false: The user is not a confirmed user.
full_namestring
Represents the full name of the user in the format specified in "name_format" key.
dobstring
Represents the date of birth of the user.
date_formatstring
Represents the user preferred date format. For instance, 'MM/dd/yyyy'.
time_formatstring
Represents the user preferred time format for the respective user. For instance, 'hh:mm a'.
statusstring
Represents the status of the user.
Possible values:
- active: The user is active.
- inactive: The user is inactive.
type__sstring
Represents the type of the user.
Possible values: Regular User, Client Portal User, Sandbox Developer User, Team User, Support User.
signaturestring
Represents the user's signature.
name_format__sstring
Represents the format of the full_name of the user. For instance, 'Salutation,First Name,Last Name'.
sort_order_preference__sstring
Represents how the records in the response are sorted based on either the last name or first name. The default sorting happens by the record IDs.
languagestring
Represents the language in which the user accesses the CRM. For instance, 'en_US'.
microsoftBoolean
Represents if the user is a Microsoft user.
Possible values:
- true: The user is a Microsoft user.
- false: The user is not a Microsoft user.
personal_accountBoolean
Represents if the user is the only user in the organization.
Possible values:
- true: The user is the only user in the organization.
- false: The user is not the only user in the organization.
IsonlineBoolean
Represents if the user is online.
Possible values:
- true: The user is online.
- false: The user is offline.
themeJSON object
Represents the theme details of the respective user.
number_separatorstring
Represents the format of the number fields. The possible values are "comma", "period" and "space".
offsetstring
Represents the user's time zone offset.
customize_infoJSON object
Stores user-specific customization settings. For example, show_right_panel, unpin_recent_item, bc_view, notes_desc, and so on.
status_reason__sstring
Used for Portal Users' status reasons. For example, if a Portal User updates their email, their account may be disabled temporarily.
sandboxDeveloperBoolean
Represents if the user is a sandbox developer.
decimal_separatorstring
Represents the format of the decimal separator. The possible values are "comma" and "period".

Possible Errors

REQUIRED_PARAM_MISSINGHTTP 400
You did not specify the required parameter in the API request.
Resolution: Module parameter is mandatory to fetch assignment threshold. Make a GET Modules Metadata API call to get the valid module API names and specify the valid module name in the parameter.
INVALID_QUERYHTTP 400
The condition specified in the criteria parameter is invalid.
Resolution: Ensure that the criteria parameter is in the correct format. Refer to the Parameter section for more information.
EXPECTED_PARAM_MISSINGHTTP 400
You did not specify one of the expected parameters in the API request.
Resolution: Criteria parameter is mandatory to search unassigned users. Specify the criteria parameter in the API request.
NO_PERMISSIONHTTP 403
You do not have enough permission to search users without assignment thresholds.
Resolution: Contact your CRM administrator.
INVALID_MODULEHTTP 400
You provided an invalid module name in the API request.
Resolution: Make a GET Modules Metadata API call to get the valid module name and specify it in the parameter.
NOT_SUPPORTEDHTTP 400
You provided an invalid module in the API request.
Resolution: Assignment Threshold is supported only for Leads, Contacts, Accounts, Deals, Cases and custom modules. Specify a valid module name in the parameter.
FEATURE_NOT_SUPPORTEDHTTP 400
Your CRM edition does not support this feature.
Resolution: Assignment Threshold is supported in Professional and above editions. Upgrade your CRM edition to use this feature.
API_NOT_SUPPORTEDHTTP 400
You specified an invalid or lower version in the API request.
Resolution: Assignment Threshold is supported from API version v8 and above. Specify a valid version in the API request.
PATTERN_NOT_MATCHEDHTTP 400
The value provided for the type parameter is invalid.
Resolution: The type parameter value should be one of the following: AllUsers, ActiveUsers, DeactiveUsers, ConfirmedUsers, NotConfirmedUsers, DeletedUsers, ActiveConfirmedUsers, AdminUsers, ActiveConfirmedAdmins and CurrentUser.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one.
Resolution: You have specified an invalid HTTP method to access the API URL.
Specify a valid request method. Refer to the endpoints section of the API.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to search users without assignment threshold. Create a new token with valid scope. Refer to scope section of the API.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one.
Resolution: The request URL specified is incorrect. Specify a valid request URL.Refer to the request URL section of the API.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "users": [
        {
            "country": "US",
            "name_format__s": "Salutation,First Name,Last Name",
            "language": "en_US",
            "microsoft": false,
            "$shift_effective_from": null,
            "Currency": "INR",
            "id": "1862079000000440001",
            "state": null,
            "fax": null,
            "country_locale": "en_US",
            "sandboxDeveloper": false,
            "zip": null,
            "decimal_separator": "Period",
            "created_time": "2022-12-02T11:31:54+05:30",
            "time_format": "hh:mm a",
            "offset": 19800000,
            "profile": {
                "name": "Administrator",
                "id": "1862079000000015972"
            },
            "created_by": {
                "name": "Patricia Boyle",
                "id": "1862079000000440001"
            },
            "zuid": "72710344",
            "full_name": "Patricia Boyle",
            "phone": null,
            "dob": null,
            "sort_order_preference__s": "First Name,Last Name",
            "status": "active",
            "type__s": "Regular User",
            "role": {
                "name": "CEO",
                "id": "1862079000000015966"
            },
            "customize_info": {
                "notes_desc": null,
                "show_right_panel": null,
                "bc_view": null,
                "show_home": false,
                "show_detail_view": true,
                "show_left_panel": true,
                "unpin_recent_item": null
            },
            "city": null,
            "signature": null,
            "locale": "en_US",
            "personal_account": false,
            "Isonline": true,
            "default_tab_group": "0",
            "Modified_By": {
                "name": "Patricia Boyle",
                "id": "1862079000000440001"
            },
            "street": null,
            "$current_shift": null,
            "alias": null,
            "theme": {
                "normal_tab": {
                    "font_color": "#FFFFFF",
                    "background": "#222222"
                },
                "selected_tab": {
                    "font_color": "#FFFFFF",
                    "background": "#222222"
                },
                "new_background": null,
                "background": "#F3F0EB",
                "screen": "fixed",
                "type": "default"
            },
            "first_name": "Patricia",
            "email": "patricia.boyle@zylker.com",
            "status_reason__s": null,
            "website": null,
            "Modified_Time": "2025-02-27T11:45:36+05:30",
            "$next_shift": null,
            "mobile": null,
            "last_name": "Boyle",
            "time_zone": "Asia/Kolkata",
            "number_separator": "Comma",
            "confirm": true,
            "date_format": "MMM d, yyyy"
        }
    ],
    "info": {
        "per_page": 200,
        "count": 1,
        "page": 1,
        "more_records": false
    }
}