Kaizen #48 - Related Lists and Related Records #API

Kaizen #48 - Related Lists and Related Records #API

Hello everyone!
Welcome back to another post in the Kaizen series.
This week, we will discuss everything about Related lists and records.

In this post, we will cover the following:
  1. What are related lists and related records in Zoho CRM?
  2. How to retrieve metadata of related lists?
  3. How to fetch the records of a related list?
  4. How to add/update records to a related list?
  5. How to delete a record from a related list?
1. What are related lists and related records in Zoho CRM?
A record usually contains extra information such as notes, attachments, related products, deals, contacts etc.
This additional information can belong to any module such as products, deals, and so on. These modules are categorized as related lists, and the records in each of these related lists are called related records.



Note
Notes and attachments are the related lists available for all modules, by default. The other related lists depend on the lookup fields you have in a module. For example, "Deals" is a related list in the Contacts module, by default, because the Deals module has the default lookup field "Contact Name".

2. How to retrieve metadata of the related lists?

Request URL: {api-domain}/crm/v2/settings/related_lists?module={module_API_name}
Request method: GET
The response is an array of JSON objects; one for each related list. Note the API name of the related list. We will use this API name while we add related records to this related list.

Sample Response



Response JSON

Key
Data Type
Description
sequence_number
String
The position of the related list in the UI.
display_label
String
The display name of the related list either in English or the language in the user's locale.
api_name
String
The API name of the related list.
module
String
The API name of the module that the related list belongs to.
name
String
The name of the related list in the English language.
id
String
The unique ID of the related list.
href
String
The URL to call the related list API.
type
String
Represents whether the related list is a default one or formed through a lookup field in the parent module.

3. How to fetch the records of a related list?
Use the Get Related Records API.

Request URL: {api-domain}/crm/v2/{module_api_name}/{record_id}/{related_list_api_name}
Request method: GET

Sample response



4. How to add/update records to a related list?
When you create a lookup field in the parent module, it automatically creates a related list in the child module. For example, the lookup field "Contact Name" in the Deals module creates the related list "Deals" in the Contacts module.
Similarly, the lookup field "Account" in the Products module creates the related list "Related_Products" in the Accounts module.
To add records to the related list, use the Update Related Records API.

Supported modules
The following combination represents the modules you can create a relate each other with.
  • Campaigns to Leads or Contacts and vice versa.
  • Products to Leads, Accounts, Contacts, Potentials, or Price Books and vice versa.
Request URL: {api-domain}/crm/v2/{module_API_name}/{record_id}/{related_list_API_name}/{related_record_id}
Request Method: PUT

Now, to add a product to the related list Related_Products in the Accounts module, the URL will be
{api-domain}/crm/v2/Accounts/account_ID/Related_Products/product_ID

Sample Response



Note
  • You can get the API name of the related list from the Get Related List Metadata API.
  • While updating the related records, if you specify the related record ID in the request URL, then you must send an empty JSON object in the body.
  • If you do not specify the related record ID in the request URL, you must specify the ID in the request body.
  • The "href" key in the related list metadata API gives you the request URL to update the records of the related list.
  • You can add or update a maximum of 100 records to a related list per API call.
Special inputs while updating the related records
When you update the related records of Notes, Deals, or Price_Books, you must send additional data in the input body. Otherwise, the system throws the INVALID_DATA error. The following table gives you the expected input for each of these modules.

Related List
Expected Input
Notes
Note_Content, Note_Title
Price_Books
list_price
Deals (as a related list in Contacts)
Contact_Role (the ID of the contact role)

5. How to delete the records from a related list?
Use the Delink API.

Supported modules
The following combination represents the modules you can dissociate the related records from.
  • Campaigns to Leads or Contacts and vice versa.
  • Products to Leads, Accounts, Contacts, Potentials, or Price Books and vice versa.
Request URL:
To delete a single related record -  {api-domain}/crm/v2/{module_api_name}/{record_id}/{related_list_api_name}/{related_record_id}

To delete multiple related records -  {api-domain}/crm/v2/{module_api_name}/{record_id}/{related_list_api_name}?ids={comma_separated_related_record_ids}
Request method: DELETE

Sample response



Note
You can delete a maximum of 100 related records per API call.

We hope you found this post useful. Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.

Cheers!




    Access your files securely from anywhere

        Zoho Developer Community




                                  Zoho Desk Resources

                                  • Desk Community Learning Series


                                  • Digest


                                  • Functions


                                  • Meetups


                                  • Kbase


                                  • Resources


                                  • Glossary


                                  • Desk Marketplace


                                  • MVP Corner


                                  • Word of the Day



                                      Zoho Marketing Automation


                                              Manage your brands on social media



                                                    Zoho TeamInbox Resources

                                                      Zoho DataPrep Resources



                                                        Zoho CRM Plus Resources

                                                          Zoho Books Resources


                                                            Zoho Subscriptions Resources

                                                              Zoho Projects Resources


                                                                Zoho Sprints Resources


                                                                  Qntrl Resources


                                                                    Zoho Creator Resources



                                                                        Zoho Campaigns Resources


                                                                          Zoho CRM Resources

                                                                          • CRM Community Learning Series

                                                                            CRM Community Learning Series


                                                                          • Kaizen

                                                                            Kaizen

                                                                          • Functions

                                                                            Functions

                                                                          • Meetups

                                                                            Meetups

                                                                          • Kbase

                                                                            Kbase

                                                                          • Resources

                                                                            Resources

                                                                          • Digest

                                                                            Digest

                                                                          • CRM Marketplace

                                                                            CRM Marketplace

                                                                          • MVP Corner

                                                                            MVP Corner





                                                                              Design. Discuss. Deliver.

                                                                              Create visually engaging stories with Zoho Show.

                                                                              Get Started Now