Get Records Using External ID

Purpose

To fetch the records in a module using external IDs.

Request Details

Request URL

https://www.zohoapis.com/crm/v2.1/{module_api_name}

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Meetings, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, Custom, and Activities

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, accounts, contacts, deals, campaigns, tasks, cases, events, calls, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, and custom

Possible operation types

ALL - Full access to the record
READ - Get records from the module

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2.1/Contacts/{external_field_value}"
-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 the external field in this module.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2.1/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": null,
            "Full_Name": "Test Contact 1",
            "Last_Name": "Test Contact 1",
            "External_Contact_ID": "externalcontact1",
            "Account_Name": {
                "name": "Test Account1",
                "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 "ids" parameter fetches the records with the external values externalcontact1 and externalcontact2.

Sample Request

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

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": null,
            "Full_Name": "Contact 2",
            "Last_Name": "Contact 2",
            "External_Contact_ID": "externalcontact2",
            "Account_Name": {
                "name": "Account 2",
                "id": "111111000000101039"
            },
            "id": "111111000000101018",
            "OrgExternal": "orgcontact2"
        },
        {
            "First_Name": null,
            "Full_Name": "Test Contact 1",
            "Last_Name": "Test Contact 1",
            "External_Contact_ID": "externalcontact1",
            "Account_Name": {
                "name": "Test Account1",
                "id": "111111000000087057"
            },
            "id": "111111000000101004",
            "OrgExternal": "orgcontact1"
        }
    ],
    "info": {
        "per_page": 2,
        "count": 2,
        "page": 1,
        "more_records": false
    }
}