Create Custom Links

Custom links in Zoho CRM are user-defined hyperlinks that you can add to record detail pages, allowing users to navigate to external URLs or internal pages directly from within a CRM record. They act as shortcuts that pass CRM record data (like contact name, email, or account ID) as parameters in the URL, making it easy to open related tools, pages, or systems in context.
Examples
A LinkedIn lookup link that pre-searches a lead's name: https://www.linkedin.com/search/results/people/?keywords={Lead.Full_Name}
An internal dashboard link that opens a reporting tool scoped to a specific account: https://analytics.yourcompany.com/dashboard?account_id={Account.ID}

Purpose

To add a custom link to a module.

Endpoints

  • POST /settings/custom_links

Request Details

Request URL

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

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.custom_links.ALL
(or)
ZohoCRM.settings.custom_links.CREATE

Parameters

  • modulestring, mandatory

    Represents the API name of the module for which you want to create a custom link. Use the Get Modules API to get the API name of the module.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/custom_links?module=Leads"
-X POST
-d "@input.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Request JSON Keys

  • namestring, optional

    Represents the name of the custom link. Accepts up to 100 alphanumeric characters.

  • profilesJSON object, mandatory

    Each JSON object in this array represents the name and ID of the profile that can have access to the custom links. Accepts up to 200 profile JSON objects. Use the Get Profiles API to get the ID and name of the profiles.

  • urlstring, mandatory

    Represents the URL you want to create as a custom link. Accepts up to 3000 alphanumeric characters. Example: https://www.example.com/

  • url_encodingstring, mandatory

    Represents the URL encoding type for the custom link. Accepted values are UTF-8 (Unicode), UTF-16 (Unicode), ISO-8859-1, ISO-8859-9 (Turkish), GB2312 (Simplified Chinese), Big5 (Traditional Chinese), Shift_JIS (Japanese).

  • user_typesJSON array, optional

    Each JSON object in this array represents the ID and name of the user types you want to give access to this custom link. Use the Get User Types API to get the name and ID of the user groups in your org. You can have a maximum of 200 user types in this array.

Sample Input

Copied{
    "custom_links": [
        {
            "name": "LinkedIn",
            "profiles": [
                {
                    "id": "554023000000015975"
                }
            ],
            "user_types": [
                {
                    "id": "554023000006082055"
                }
            ],
            "url": "https://linkedin.com/userA",
            "url_encoding": "UTF-8",
            "description": "description_content"
        }
    ]
}

Possible Errors

  • MANDATORY_NOT_FOUNDHTTP 400

    You have not specified one or more mandatory fields in the input.
    Resolution: "name", "profiles", "url", "url_encoding" are the mandatory keys in the input. Refer to the details key in the response for the missing key.

  • MANDATORY_NOT_FOUNDHTTP 400

    You have not specified "custom_links" in the input.
    Resolution: "custom_links" is the root key in the input body. Refer to the sample section.

  • REQUIRED_PARAM_MISSINGHTTP 400

    You have not included the "module" parameter in the request.
    Resolution: "module" is a mandatory parameter in the request.

  • INVALID_DATAHTTP 400

    You have specified invalid data in the input.
    Resolution: Refer to the "details" key int he response for the API name and JSON path of the invalid key. Refer to the Request JSON section for the input keys and their datatypes.

  • LIMIT_EXCEEDEDHTTP 400

    You have created more custom links than the allowed limit.
    Resolution: You can create a maximum of 10 custom links in that module.

  • DUPLICATE_DATAHTTP 400

    A custom link with the specified name already exists in the module.
    Resolution: Specify a unique name for the custom link. Refer to the details key in the response for the conflicting field.

  • INVALID_REQUEST_METHODHTTP 400

    The request method is incorrect.
    Resolution: Use the HTTP POST method to make this API call.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    The access token you have used to make this API call does not have the required scope.
    Resolution: Generate a new access token with the scope ZohoCRM.settings.custom_links.CREATE or ZohoCRM.settings.custom_links.ALL.

  • NO_PERMISSIONHTTP 403

    You do not have permission to create custom links.
    Resolution: Contact your system administrator.

  • INVALID_URL_PATTERNHTTP 404

    The request URL is incorrect.
    Resolution: Specify a valid request URL. Refer to the Request URL section for the right URL.

  • INTERNAL_ERRORHTTP 500

    Unexpected and unhandled exception in the server. 
    Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "custom_links": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "554023000006635005"
            },
            "message": "custom link added successfully",
            "status": "success"
        }
    ]
}