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
Copied
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
Copied
Sample Response
Copied
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
Copied
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