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
    }
}