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





                                                  Use cases

                                                  Make the most of Zoho Desk with the use cases.

                                                   
                                                    

                                                  eBooks

                                                  Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho Desk.

                                                   
                                                    

                                                  Videos

                                                  Watch comprehensive videos on features and other important topics that will help you master Zoho Desk.

                                                   
                                                    

                                                  Webinar

                                                  Sign up for our webinars and learn the Zoho Desk basics, from customization to automation and more

                                                   
                                                    
                                                  • Desk Community Learning Series


                                                  • Meetups


                                                  • Ask the Experts


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner




                                                            • Sticky Posts

                                                            • Kaizen #197: Frequently Asked Questions on GraphQL APIs

                                                              🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
                                                            • Kaizen #198: Using Client Script for Custom Validation in Blueprint

                                                              Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
                                                            • Celebrating 200 posts of Kaizen! Share your ideas for the milestone post

                                                              Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQs
                                                            • Kaizen #193: Creating different fields in Zoho CRM through API

                                                              🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.
                                                            • Client Script | Update - Introducing Commands in Client Script!

                                                              Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands


                                                            Manage your brands on social media



                                                                  Zoho TeamInbox Resources



                                                                      Zoho CRM Plus Resources

                                                                        Zoho Books Resources


                                                                          Zoho Subscriptions Resources

                                                                            Zoho Projects Resources


                                                                              Zoho Sprints Resources


                                                                                Qntrl Resources


                                                                                  Zoho Creator 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


                                                                                            Zoho Show Resources


                                                                                              Zoho Writer Writer

                                                                                              Get Started. Write Away!

                                                                                              Writer is a powerful online word processor, designed for collaborative work.

                                                                                                Zoho CRM コンテンツ








                                                                                                  Nederlandse Hulpbronnen


                                                                                                      ご検討中の方




                                                                                                            • Recent Topics

                                                                                                            • Elevate your CX delivery using CommandCenter 2.0: Simplified builder; seamless orchestration

                                                                                                              Most businesses want to create memorable customer experiences—but they often find it hard to keep them smooth, especially as they grow. To achieve a state of flow across their processes, teams often stitch together a series of automations using Workflow
                                                                                                            • Custom Buttons for Mass Actions

                                                                                                              Hello everyone, We’ve just made Custom Buttons in Zoho Recruit even more powerful! You can now create Bulk Action Buttons that let you perform actions on multiple records at once, directly from the List View. What’s new? Until now, custom buttons were
                                                                                                            • Zoho Assist not rendering NinjaTrader chart properly

                                                                                                              Hi everyone. Just installed and testing Zoho Assist. I want to display my laptop' screen (Windows 11) on a monitor connected to my Mac mini. The laptop is running a stock trading program called NinjaTrader. Basically, when running, this program displays
                                                                                                            • Involved account types are not applicable when create journals

                                                                                                              { "journal_date": "2016-01-31", "reference_number": "20160131", "notes": "SimplePay Payroll", "line_items": [{ "account_id": "538624000000035003", "description": "Net Pay", "amount": 26690.09, "debit_or_credit": "credit" }, { "account_id": "538624000000000403", "description": "Gross", "amount": 32000, "debit_or_credit": "debit" }, { "account_id": "538624000000000427", "description": "CPP", "amount": 1295.64, "debit_or_credit": "debit" }, { "account_id": "538624000000000376", "description":
                                                                                                            • Question regarding import of previous deals...

                                                                                                              Good afternoon, I'm working on importing some older deal records from an external sheet into the CRM; however, when I manually click "Add New Deal" and enter the pertinent information, the deal isn't appearing when I look at the "Deals" bar on the account's
                                                                                                            • Auto Capitalize First Letter of Words

                                                                                                              Hi I am completely new to ZOHO and am trying to build a database. How can i make it when a address is entered into a form field like this: main st it automatically changes is to show: Main St Thank You
                                                                                                            • Adding Social Media Buttons to Basic Campaigns

                                                                                                              Hi, I'm quote new to using Zoho Campaigns and I can't work out how to add Social Media Buttons into my basic campaign? In MailChimp there's a button that brings the icons into your campaign for you. I've tried adding the social media icons as 'buttons' in Zoho but it's not looking great. Can anyone help? Thanks!
                                                                                                            • Dropshipping Address - Does Not Show on Invoice Correctly

                                                                                                              When a dropshipping address is used for a customer, the correct ship-to address does not seem to show on the Invoice. It shows correctly on the Sales Order, Shipment Order, and Package, just not the Invoice. This is a problem, because the company being
                                                                                                            • An Exclusive Session for Zoho Desk Users: AI in Zoho Desk

                                                                                                              A Zoho Community Learning Initiative Hello everyone! This is an announcement for Zoho Desk users and anyone exploring Zoho Desk. With every nook and corner buzzing, "AI's here, AI's there," it's the right time for us to take a closer look at how the AI
                                                                                                            • Best way to schedule bill payments to vendors

                                                                                                              I've integrated Forte so that I can convert POs to bills and make payments to my vendors all through Books. Is there a way to schedule the bill payments as some of my vendors are net 30, net 60 and even net 90 days. If I can't get this to work, I'll have
                                                                                                            • Link(s) between Notes

                                                                                                              Hello Everyone, It would be great if links could be created between notes. Let's say we have 5 Notes A, B, C , D, E. I would like to be able to link Note A to Note B but not in other way, so no link appears in Note B linking to Note A. An so on, linking
                                                                                                            • Regex in Zoho Mail custom filters is not supported - but it works!

                                                                                                              I recently asked Zoho for help using regex in Zoho Mail custom filters and was told it was NOT supported. This was surprising (and frustrating) as regex in Zoho Mail certainly works, although it does have some quirks* To encourage others, here are 3 regex
                                                                                                            • Need Easy Way to Update Item Prices in Bulk

                                                                                                              Hello Everyone, In Zoho Books, updating selling prices is taking too much time. Right now we have to either edit items one by one or do Excel export/import. It will be very useful if Zoho gives a simple option to: Select multiple items and update prices
                                                                                                            • Feature Request: Assign Documents to Already Entered Bills, Expenses, Invoices, etc.

                                                                                                              Hi Zoho Team, We are regular users of the Documents module in Zoho Books and appreciate its ability to keep financial records well-organized. However, we’ve noticed a limitation: There is no way to attach a document from the "Documents > Files" section
                                                                                                            • I don't see any WITHDRAWL transaction at all

                                                                                                              Hi I manually imported my bank statement to Zoho books today and I am a complete newbie. I have been reading the knowledgebase but unable to fix this. I only see "Uncategorized 91 DEPOSIT transactions". I don't see any WITHDRAWL transaction at all. Also,
                                                                                                            • Shared inbox unable to see replies

                                                                                                              Hi we are a small company me and someone else, we have a shared inbox for our sale@ and contact@ however we have this issue where by if i reply to an email or the other person reply to the email, it does not show it to them and therefore we end up replying
                                                                                                            • Sync desktop folders instantly with WorkDrive TrueSync (Beta)

                                                                                                              Keeping your important files backed up and accessible has never been easier! With WorkDrive desktop app (TrueSync), you can now automatically sync specific desktop folders to WorkDrive Web, ensuring seamless, real-time updates across devices. Important:
                                                                                                            • Workdrive on Android - Gallery Photo Backups

                                                                                                              Hello, Is there any way of backing up the photos on my android phone directly to a specific folder on Workdrive? Assuming i have the workdrive app installed on the phone in question. Emma
                                                                                                            • Zoho Books | Product updates | August 2025

                                                                                                              Hello users, We’ve rolled out new features and enhancements in Zoho Books. From the right sidebar where you can manage all your widgets, to integrating Zoho Payments feeds in Zoho Books, explore the updates designed to enhance your bookkeeping experience.
                                                                                                            • Kaizen #136 - Zoho CRM Widgets using ReactJS

                                                                                                              Hey there! Welcome back to yet another insightful post in our Kaizen series! In this post, let's explore how to use ReactJS for Zoho CRM widgets. We will utilize the sample widget from one of our previous posts - Geocoding Leads' Addresses in ZOHO CRM
                                                                                                            • 404 error at checkout

                                                                                                              Our customers are getting a 404 error at checkout. Anyone else with the same problem?
                                                                                                            • FONT Sizing in Notebook

                                                                                                              Hi Kishore - What is the status of adding font sizing to the application? I have several things that I have pasted directly into Notebook and the fonts are HUGE! I would like the ability to highlight them and reduce the font to a legible size. Nothing
                                                                                                            • Can managers Upload documents to their direct rapports?

                                                                                                              Admin employees have the ability to upload documents to employees' files; however, managers do not have add/manage button - is it possible for managers to upload their direct reports' documents, such as absence documents or 121 documents. Is there something
                                                                                                            • Leave balance display for next year

                                                                                                              Is there a way to not have a rollover or not limit the leave balance depending on the date. For example an employee has 10 days leave balance and wants to apply for January leave in December. They cant because the rollover doesnt show the leave balance
                                                                                                            • Please add an “Auto-Apply Unused Credits” toggle

                                                                                                              Hello — please add a simple org-level option to automatically apply unused credits (credit notes, excess payments, retainers) to new invoices and/or bills. An ON/OFF toggle with choices “invoices”, “bills”, or “both” would save lots of manual work for
                                                                                                            • Zoho Books not working/loading

                                                                                                              Hi! I haven't been able to access/load Zoho Books for the past hours. I get a time out (and it is not due to my internet connection). Could you please check this asap? Thank you!
                                                                                                            • WhatsApp Channels in Zoho Campaigns

                                                                                                              Now that Meta has opened WhatsApp Channels globally, will you add it to Zoho Campaigns? It's another top channel for marketing communications as email and SMS. Thanks.
                                                                                                            • Introducing Profile Summary: Faster Candidate Insights with Zia

                                                                                                              We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiring
                                                                                                            • Custom Fields with Data Types for Expense and Payments Received in Zoho Books

                                                                                                              Hi all, We are glad to present to you, the option to create Custom Fields for the Expense and Payments received modules in Zoho Books. This also comes with an icing on top of it - Yes, the custom fields can now be created with different data types. Types like Text, Number, Decimal, Amount, Auto Number and Check Box are supported as of now. Rush to the gear icon at the top right corner, select 'More Settings', choose 'Preferences' in the left pane. Click the Expense/Payment preferences where you can
                                                                                                            • Custom Fonts in Zoho CRM Template Builder

                                                                                                              Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities if
                                                                                                            • [Webinar] Automate sales and presales workflows with Writer

                                                                                                              Sales involves sharing a wide range of documents with customers across the presales, sales, and post-sales stages: NDAs, quotes, invoices, sales orders, and delivery paperwork. Generating and managing these documents manually slows down the overall sales
                                                                                                            • Follow-up emails via Workflow Automation not staying in the same thread

                                                                                                              Dear Zoho Support Team, I am currently using Workflow Automation in Zoho Campaigns to send follow-up emails. In my test case, I noticed the following behavior: All emails in the automation have the same subject line. If the follow-up email is sent within
                                                                                                            • Zoho Cliq - Incident alert (Server outage - IN DC) | August 28

                                                                                                              We've received server down alerts and are currently investigating the issue (IN DC) to find the root cause. Our team is actively working to restore normal operations at the earliest. Status: Under investigation Start time: 09:44:21 AM IST Affected location:
                                                                                                            • Claude + MCP Server + Zoho CRM Integration – AI-Powered Sales Automation

                                                                                                              Hello Zoho Community 👋 I’m excited to share a recent integration we’ve worked on at OfficehubTech: ✅ Claude + MCP Server + Zoho CRM This integration connects Zoho CRM with Claude AI through our custom MCP Server, enabling intelligent AI-driven responses
                                                                                                            • How to conditionally embed an own internal widget with parameters in an html snippet?

                                                                                                              Hello everyone, I'm trying to create a dynamic view in a page using an HTML snippet. The goal is to display different content based on a URL parameter (input.step). I have successfully managed to conditionally display different forms using the following
                                                                                                            • Sync more than one Workdrive

                                                                                                              Hello Please I'm facing some difficulties since some days. In my company we have many zoho accounts in different organisations. And I have to find a way to sync all these Workdrives. I spend many hours to search it on zoho Workdrive but no solution. Could someone help me ? Any idea how I can achieve it ? Thanks in advance. Regards
                                                                                                            • How can I see content of system generated mails from zBooks?

                                                                                                              System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.
                                                                                                            • Limitations on editing a message in Cliq

                                                                                                              Hi I've checked the documentations and there's no mention of how many times a message can be edited. When trying with code, I get various numbers such as ~1000 edits or so. Please mention if there's a limit on how many times one can change a message via
                                                                                                            • Problem with reports due to "Connected" items change - Yes this IS a problem

                                                                                                              Now that the change has been made to use "connected" items I can no longer run the reporting I need in CRM. I should be able to start with Deals as the parent, connect down to the Account (Account_Name) on the deal as the child, then to any child items
                                                                                                            • CRM x WorkDrive: File storage for new CRM signups is now powered by WorkDrive

                                                                                                              Availability Editions: All DCs: All Release plan: Released for new signups in all DCs. It will be enabled for existing users in a phased manner in the upcoming months. Help documentation: Documents in Zoho CRM Manage folders in Documents tab Manage files
                                                                                                            • Next Page