Get Records Using External ID
Purpose
To fetch the records in a module using external IDs.
Endpoints
- GET /{module_API_name}/{external_field_value}
Request Details
Request URL
To fetch by external field value:
{api-domain}/crm/{version}/{module_API_name}/{external_field_value}
Supported modules
Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Meetings, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, Appointments, Services and Activities
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
X-EXTERNAL: {module_API_name}.{external_field_API_name}
Scope
ZohoCRM.modules.ALL
(or)
ZohoCRM.modules.{module_api_name}.{operation_type}
Possible module names
Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Events, Calls, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, Appointments__s, Services__s and custom
Possible operation types
ALL - Full access to the record
READ - Get records from the module
Parameters
- fieldsstring, optional
Specify the API names of the fields to be included in the response. You can list multiple field API names, separated by commas.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/1749243232"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: {base_module_API_name}.{external_field_API_name}"Fetching a record through the external field's value
In this example, Contacts is the base module's API name, External_Contact_ID is the API name of the external field, and externalcontact1 is the value of this external field for a record in this Contacts module.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts/externalcontact1?fields=External_Contact_ID,Last_Name,First_Name,Full_Name,Account_Name,OrgExternal&per_page=2"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"Sample Response
Copied{
"data": [
{
"First_Name": Patricia,
"Full_Name": "Boyle",
"Last_Name": "Patricia Boyle",
"External_Contact_ID": "externalcontact1",
"Account_Name": {
"name": "Test Account",
"id": "111111000000087057"
},
"id": "111111000000101004",
"OrgExternal": "orgcontact1"
}
]
}Fetching the records using the "ids" parameter
In this example, Contacts is the base module's API name, External_Contact_ID is the API name of the external field. The request using "ids" parameter retrieves records with the external values externalcontact1 and externalcontact2.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/Contacts?ids=externalcontact1,externalcontact2&fields=External_Contact_ID,Last_Name,First_Name,Full_Name,Account_Name,OrgExternal&per_page=2"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-H "X-EXTERNAL: Contacts.External_Contact_ID"Possible Errors
- NO_CONTENTHTTP 204
There is no data for the ID specified or there is no matching record in the given module.
Resolution: Create a record with the given external value or try again with a valid external ID. - INVALID_DATAHTTP 400
You have specified and invalid external fields in header.
Resolution: Specify a valid external field for the X-EXTERNAL header. - 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 required scopes for this API. Refer to the Scope section at the beginning of this page for the list of required scopes. - AUTHENTICATION_FAILUREHTTP 401
You have not authorized the API call with valid access token.
Resolution: Include a valid access token in the request header to authorize the API call. - INVALID_URL_PATTERNHTTP 404
The request URL is incorrect, or you have missed the X-EXTERNAL header in the request.
Resolution: Create a record with the given external value or try again with a valid external ID.
Make sure to include X-EXTERNAL header in the request and try again. - INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.
Note
- You cannot fetch records with respect to the external field value set by another user.
- All parameters in the Get List of Records(without external ID) are supported here.
Sample Response
Copied{
"data": [
{
"First_Name": Patricia,
"Full_Name": "Boyle",
"Last_Name": "Patricia Boyle",
"External_Contact_ID": "externalcontact1",
"Account_Name": {
"name": "Account 2",
"id": "111111000000101039"
},
"id": "111111000000101018",
"OrgExternal": "orgcontact2"
},
{
"First_Name": Pat,
"Full_Name": "Boyle",
"Last_Name": "Pat Boyle",
"External_Contact_ID": "externalcontact2",
"Account_Name": {
"name": "Test Account1",
"id": "111111000000087057"
},
"id": "111111000000101004",
"OrgExternal": "orgcontact1"
}
],
"info": {
"per_page": 2,
"count": 2,
"page": 1,
"more_records": false
}
}