Kaizen #66 - Contact Roles #API

Kaizen #66 - Contact Roles #API

Hi everyone! Welcome to another Kaizen week!!
This week, we will be discussing the Contact Roles APIs in Zoho CRM.

What are Contact Roles in Zoho CRM?

      The Contact Roles related list is a powerful feature in Zoho CRM that allows you to define the role of a contact in a deal, and to associate multiple contacts with a Deal.
      The Contact Roles lets you track and manage various contacts within a prospective organization, and understand their roles to have targeted and effective discussions. For example, when you schedule a meeting with the head of the department, it is important to explain the product features and functionalities, but it is imperative to discuss the cost-saving benefits with a financial manager. Likewise, you can choose to address the product features with a product manager, present technical specifications to an IT manager, or review legal or compliance considerations with a legal manager. With Contact roles, you can thus have the most relevant and productive discussions as you work on a deal.
There are a few Contact Roles like Decision Maker, Product Management, Purchasing etc that are available by default. You can also customize them according to the specific business requirements. 

1. Retrieving Contact Roles via API

Using the Get Contact Roles API, you can get the list of contact roles configured in your organization.

Request method : GET
Request URL to retrieve all Contact Roles : {api-domain}/crm/{version}/Contacts/roles
Request URL to retrieve a specific Contact Role : {api-domain}/crm/{version}/Contacts/roles/{contact_role_id}

Sample Request and Response


Response Keys

 Key
 Description
 sequence_number
 Position of the contact role in the picklist in CRM UI
 name
 Name of the contact role
 id
 Unique ID of the contact role

2. Adding new Contact Roles via API

      Using the Insert Contact Roles API you can create a new contact role to fit your business need. For example, you are working on a deal and have been in touch with several contacts throughout the sales process. As you near the end of the negotiation, you start talking to the legal department of the prospective organization to finalize the terms of the contract. You might want to add the legal manager as a contact role, and associate the respective contact with the role.
You can add up to 100 contact roles in a single API call.

Request method : POST
Request URL : {api-domain}/crm/{version}/Contacts/roles

Input Keys

 Key
 Description
 name
 string, mandatory
 The name of the contact role
 sequence_number
 integer, optional
 The position of the contact role in the picklist in CRM UI

Sample Request and Response



If you add a new contact role in Zoho CRM to a position that is already occupied, the existing contact role will be moved down one position to make room for the new role.

3. Updating Contact Roles via API

You can update the name and sequence number of up to 100 contact roles using the Update Contact Roles API.

Request method : PUT
Request URL to update more than one Contact Role : {api-domain}/crm/{version}/Contacts/roles
Request URL to update a specific Contact Role : {api-domain}/crm/{version}/Contacts/roles/{contact_role_id}

Input Keys

 Key Description
 id
 string, mandatory
 U​​nique ID of the contact role.
 This key is mandatory if you have not specified the id in the URL.
 name
 string, optional
 Name of the contact role
 sequence_number
 integer, optional
 The position of the contact role in the picklist in CRM UI

Sample Request and Response


4. Deleting Contact Roles via API

If a contact role is no longer relevant, you may need to delete that contact role from your organization. 

Request method : DELETE
Request URL to delete more than one Contact Role : {api-domain}/crm/{version}/Contacts/roles?ids={contact_role_id1,contact_role_id2,..}
Request URL to delete a specific Contact Role : {api-domain}/crm/{version}/Contacts/roles/{contact_role_id}

To delete multiple contact roles in a single API call, you must include the ids parameter. The API allows you to delete up to 100 contact roles at a time.

Sample Request and Response



Now that we have learnt how to create, fetch, update and delete contact roles, let us see how to associate a contact role with a deal. 

5. Associate Contact Role with a Deal

      You can add a contact to a deal and associate the same with a contact role. You can add only one contact role to the deal in a single API call. 
      Consider a scenario where you are working on a deal with a medium-sized company and have been in contact with the company's sales manager throughout the sales process. Towards the end, you would need to speak with the company's legal advisor to review the contract terms and compliance considerations. You can use the contact roles feature, and associate the contact with the deal. 

Request method : PUT
Request URL : {api-domain}/crm/{version}/Deals/{deal_id}/Contact_Roles/{contact_id}

Input Keys

 Key Description
 id
 string, mandatory if name is not specified
 Unique ID of the contact role.
 name
 string, mandatory if id is not specified
 Name of the contact role

You must specify either the name or the id, or both in the input body. 

Sample Request and Response



6. Fetch Contact Roles of a specific Deal via API

      If you are working on a deal with a large enterprise, you may be in contact with several individuals throughout the sales process. As the deal nears closure, you may want to review all contact roles to ensure you have covered all necessary discussions and are aligned with the right people. You can use this API to fetch all contact roles associated with the Deal for assistance with the review.

Request method : GET
Request URL to get all Contact Roles associated with the Deal : {api-domain}/crm/{version}/Deals/{deal_id}/Contact_Roles
Request URL to get a specific contact role associated with the Deal : {api-domain}/crm/{version}/Deals/{deal_id}/Contact_Roles/{contact_id}
Request URL to get multiple contact roles associated with the Deal : {api-domain}/crm/{version}/Deals/{deal_id}/Contact_Roles?ids={contact_id1,contact_id2,...}

Sample Request and Response


7. Removing a contact role from a deal

      As you progress through the sales process, one of the stakeholders may no longer be involved in the deal. In this case, you may want to delete this contact role from the deal to ensure that you are only working with the relevant set of stakeholders.  Using the API, you can remove up to 100 contact roles from a specific deal.

Request method : DELETE
Request URL : {api-domain}/crm/{version}/Deals/{deal_id}/Contact_Roles/{contact_id}
Request URL to remove more than one contact role from a Deal : {api-domain}/crm/{version}/Deals/{deal_id}/Contact_Roles?ids={contact1,contact2,..}

Sample Request and Response



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. 

We will be back next year with more interesting topics. Wishing you a Happy New Year!

    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