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
}
}Show full
Show less
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"
}
]
}