Create Custom Module

Purpose

To create a new custom module in Zoho CRM.

Endpoints

POST /settings/modules

Request Details

Request URL

{api-domain}/crm/{version}/settings/modules

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope = ZohoCRM.settings.modules.CREATE (or)
scope = ZohoCRM.settings.modules.ALL (or)
scope = ZohoCRM.settings.ALL

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v6/settings/modules"
-X POST
-d "@input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Common Input JSON Keys

plural_labelstring, mandatory
Represents the unique plural name of the module. A maximum of 25 characters, including spaces, is allowed. Note that the value of this field should not be empty, and only letters, numbers, and spaces are supported.
singular_labelstring, mandatory
Represents the unique singular name of the module. A maximum of 25 characters, including spaces, is allowed. Note that the value of this field should not be empty, and only letters, numbers, and spaces are supported.
profilesstring, mandatory
Specify the profiles that should have access to the module. It is mandatory to specify at least one profile. Refer to the GET Profiles API to retrieve the profiles available in your org.
api_namestring, optional
Represents the unique API name of the module. A maximum of 50 characters are allowed which can include alphabets, numbers, spaces, and underscore.
- The API name should start with an English alphabet character.
- The API name should not end with an underscore (_) and should not contain two consecutive underscores (__).
Note that if you skip this key, the system will generate the API name based on the value given in the plural_label field.
display_fieldJSON object, optional
Represents the details of the display field of a module. There are two supported values for the "display_field" key.
Possible values:
autonumber - Use the autonumber data type when you want the display field to automatically generate a unique number sequence for each record. You can set the start number, prefix, and suffix for the auto-number sequence.
text - Use the text data type when you want the display field to be a text field that users can manually enter values.
The following sections are specific to each data type. Note that by default the system will generate "Text" data type for the display field.

Input JSON Keys for "Auto Number" ("data_type" : "autonumber")

display_fieldJSON object, optional
Represents the details of the display field of a module.
- field_labelstring, mandatory (either field_label or data_type is mandatory when you specify the display field)
  Represents the display name of the field.
- data_typestring, mandatory (either data_type or field_label is mandatory when you specify the display field)
  Represents the data type of the field.
- auto_numberJSON object, mandatory
  Contains the details of the auto number field.
  - start_numberinteger, mandatory
    It specifies the starting number for the auto number sequence. A maximum of 16 digits are allowed, and only numeric characters are allowed. Ensure there are no spaces in the key.
  - prefixstring, optional
    It represents the prefix value to be added to the autonumber field value. A maximum of 50 characters are allowed, and only alphanumeric characters are allowed.
  - suffixstring, optional
    It represents the suffix value to be added to the autonumber field value. A maximum of 50 characters are allowed, and only alphanumeric characters are allowed.

Input JSON Keys for "Text" ("data_type" : "text")

display_fieldJSON object, optional
Represents the details of the display field of a module.
- field_labelstring, mandatory (either field_label or data_type is mandatory when you specify the display field)
  It represents the unique display label of the field.
- data_typestring, mandatory (either data_type or field_label is mandatory when you specify the display field)
  Represents the data type of the field.

Notes

You can create one custom module in a single API call.
You can create custom fields in the custom module using the POST Custom Field API.

Sample input for creating a module with a display label's datatype as "autonumber"

Copied{
    "modules": [
        {
            "plural_label": "Stocks",
            "singular_label": "Stock",
            "profiles": [
                {
                    "id": "2423488000000015972"
                }
            ],
            "api_name": "stock",
            "display_field": {
                "field_label": "My name field label",
                "data_type": "autonumber",
                "auto_number": {
                    "prefix": "ZOHOCRM",
                    "start_number": "1003",
                    "suffix": "BRANCH"
                }
            }
        }
    ]
}

Sample input for creating a module with a display label's datatype as "text"

Copied{
    "modules": [
        {
            "plural_label": "Zylkers",
            "singular_label": "Zylker",
            "profiles": [
                {
                    "id": "2423488000000015972"
                }
            ],
            "display_field": {
                "field_label": "Zylker",
                "data_type": "text"
            }
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
- The API name given seems to be invalid
  Resolution : Specify a valid API name.
- Invalid data type for the field given in the request body
  Resolution : Specify a valid data type for the field. Possible data types are "autonumber" or "text".
- The number of characters provided in either the plural_label or singular_label exceeds the allowed limits.
  Resolution : The singular_label and plural_label keys allow a maximum of 25 characters each.
- Invalid profile ID
  Resolution : Specify a valid Profile ID.
- Special characters are found in the singular_label or plural_label
  Resolution : Special characters are not allowed in the module singular_label and plural_label keys. Specify a valid value.
- System-defined keywords are not supported for either plural_label or singular_label
  Resolution : Specify a valid name for the module.
  The system-defined Keywords are CustomTab, CustomModule, Fileupload, Imageupload, General, Approvals, SalesInbox, Unsubscribe, CheckLists, Blueprints, ConsentForm, Datarequest, Organization, ZSURVEY, Role, Roles, Profile, Profiles, Report Folders, Report Folder, Blueprint Transitions, Blueprint States, Blueprint Logs, Blueprint Transition Logs, Blueprint State Logs Forecast Quotas, Forecast Items, Fiscal Periods, Forecast Quota, Forecast Item, Fiscal Period, Forecast Types, Forecast Type, Forecast Predictions, Forecast Prediction, Forecast Groups, Forecast Group, Locking Information, and LockingInformation.
MANDATORY_NOT_FOUNDHTTP 400
Mandatory fields are missing
Resolution: Specify all the mandatory fields to create a custom module. Refer to theInput JSON Keys section above.
DUPLICATE_DATAHTTP 400
- Duplicate values have been found for the singular_label or plural_label
  Resolution : Specify a unique value.
- Duplicate value for the api_name has been found
  Resolution : Specify a unique API name.
API_NOT_SUPPORTEDHTTP 400
The API is not supported for the requested version
Resolution: The API is supported in version 6 and above. Try from a supported version.
MINIMUM_DATA_NOT_FOUNDHTTP 400
Minimum one profile is needed
Resolution: Assign atleast one profile to a created module. The profile key should not be empty or null.
RESERVED_KEYWORD_NOT_ALLOWEDHTTP 403
System-defined keywords given for api_name key
Resolution: You have sepcified a system-defined keyword. Specify a valid name for the API name. The System-defined keywords are settings, signals, Last_Follow_Up_By, Number_Of_Followups, Last_Follow_Up_Time, First_Follow_Up_By, First_Follow_Up_Time, Notes, nearby_distance__s, Quoted_Items, Discount_Percentage__s, Discount_Type__s, ChronologicalView, nearby_distance__s, Ordered_Items, Discount_Percentage__s, ShiftHours, nearby_distance__s, Converted_Account, Converted_Contact, Converted_Deal, Converted_Potential, ChronologicalView, nearby_distance__s, Mailchimp, nearby_distance__s, Status, ChronologicalView.
NOT_SUPPORTEDHTTP 400
Module creation is not supported for the current edition
Resolution: To create a custom module, upgrade to Enterprise edition or above.
LIMIT_EXCEEDEDHTTP 400
Module creation limit has been reached for the current edition
Resolution: Upgrade to a higher edition to create more number of custom modules. See more information about edition wise limits.
EXPECTED_FIELD_MISSINGHTTP 400
One or more expected fields are missing.
Resolution: If the display_field is specified in the request body, then specify at least any one of the following keys: field_label and data_type.
DEPENDENT_FIELD_MISSINGHTTP 400
One or more dependent keys are missing for the field you specified in the request body
Resolution: Refer to the Input JSON Keys above to know the dependent keys.
NO_PERMISSIONHTTP 403
No permission to create custom module
Resolution: Contact the administrator.
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 above.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "modules": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "2423488000000834002"
            },
            "message": "module created successfully",
            "status": "success"
        }
    ]
}