Get Related Records Using External ID

Purpose

To get the related list records using external IDs.

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}/{external_value}/{related_list_api_name}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

X-EXTERNAL: {module_API_name}.{external_field_API_name}

Scope

scope=ZohoCRM.modules.all
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names

leads, deals, contacts, accounts, products, campaigns, appointments, services and pricebooks

Possible operation types

ALL - Full access to the related records
WRITE - Edit related records
GET - Fetch related records from the module

Parameters

  • fieldsstring, mandatory

    Specify the API name of the field whose details you want to receive in the response.

  • pageinteger, optional

    To get the list of records from the respective pages. Default value for page is 1.
    Possible values: Positive Integer values only.

  • per_pageinteger, optional

    To get the list of records available per page. The default and the maximum possible value is 200.
    Possible values: Positive Integer values only.

Endpoints

  • GET /{module_API_name}/{external_value}/{related_list_API_name}
Fetching all related deals in the Contacts module

  • In this example, extcontact3 is the value of the external field External_Contact_ID in the Contacts module. We will reference this field's value to fetch the deals associated to this contact.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/extcontact3/Deals?fields=Deal_Name,Stage,Closing_Date"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

Sample Response

Copied{
    "data": [
        {
            "Contact_Role": {
                "id": null
            },
            "Deal_Name": "New Deal 200",
            "Stage": "Closed Won",
            "id": "3652397000019555005",
            "Closing_Date": "2024-12-27"
        },
        {
            "Contact_Role": {
                "id": null
            },
            "Deal_Name": "Ext deal 200",
            "Stage": "Closed Won",
            "id": "3652397000019552017",
            "Closing_Date": null
        }
    ],
    "info": {
        "per_page": 200,
        "next_page_token": null,
        "count": 2,
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": null,
        "more_records": false
    }
}
Fetch a related record through the external field's value of the related record

  • In this example, externaldeal3 is the value of the external field External_Deal_ID in the Deals module. We will reference this value to fetch this related deal from the contact whose external value is extcontact3.

Possible Errors

  • NO_CONTENTHTTP 204

    There is no record for the values you have given in the request URL.
    Resolution: Specify the right values for the external fields in the request URL.

  • INVALID_DATAHTTP 400

    You have specified an invalid external ID for the base module.
    Resolution: Input the correct external ID.

  • REQUIRED_PARAM_MISSINGHTTP 400

    One of the expected parameters is missing.
    Resolution: Specify the fields parameter in the request URL.

  • INVALID_REQUEST_METHODHTTP 400

    The request method is incorrect.
    Resolution: Use the HTTP GET method to make this API call. Any other request method will result in this error.

  • AUTHORIZATION_FAILEDHTTP 400

    You do not have sufficient permission to get the related records.
    Resolution: Contact your system administrator.

  • 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 mentioned in the Scope section.

  • NO_PERMISSIONHTTP 403

    You do not have permission to get related records' data.
    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 Request

Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/extcontact3/Deals/externaldeal3"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Deals.External_Deal_ID,Contacts.External_Contact_ID"

Sample Response

Copied{
    "data": [
        {
            "Contact_Role": "111111000000026002",
            "External_Deal_ID": "externaldeal3",
            "id": "111111000000094028"
        }
    ]
}