Get Related Records Using External ID

Purpose

To get the related list records using external IDs.

Request Details

Request URL

{api-omain}/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.

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/v5/Contacts/583472934/Deals?fields=Closing_Date,Stage,Account_Name"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"

Sample Response

Copied{
    "data": [
        {
            "Contact_Role": 11112748204747392,
            "Stage": "Closed Won",
            "Account_Name": {
                "name": "Chapman",
                "id": "4876876000001036013"
            },
            "id": "4876876000002095001",
            "Closing_Date": "2022-08-09"
        }
    ],
    "info": {
        "per_page": 200,
        "next_page_token": null,
        "count": 1,
        "page": 1,
        "previous_page_token": null,
        "page_token_expiry": null,
        "more_records": false
    }
}

Fetching 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

INVALID_DATAHTTP 400
You have specified an invalid external ID for the base module.
Resolution: Input the correct external ID.
NO_CONTENTHTTP 204
You have specified an invalid ID in the URL or in the "ids" parameter.
Resolution: Input valid IDs.
REQUIRED_PARAM_MISSINGHTTP 400
One of the expected parameter is missing.
Resolution: Specify the fields parameter in the request URL.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v5/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 Respose

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