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

                                                                                                            • 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
                                                                                                            • Please Make Zoho CRM Cadences Flexible: Allow Inserting and Reordering Follow-Up Steps

                                                                                                              Sales processes are not static. We test, learn, and adapt as customers respond differently than expected. Right now, Zoho Cadences do not support inserting a new step between existing follow-ups or changing the type of an existing primary step. If I realize
                                                                                                            • Vendor Signatures Needed for Purchase Orders

                                                                                                              Hello everyone, We have a unique requirement that necessitates that Vendors & Suppliers formally acknowledge our Purchase Orders upon receipt. I was hoping that there would be an option to do so in Zoho Books, but that does not appear to be the case.
                                                                                                            • Is there an API to "File a Ticket" in Desk

                                                                                                              Hi, Is there an API to "File a Ticket" in Desk to zoho projects?
                                                                                                            • Critical Issue: Tickets Opened for Zoho Support via the Zoho Help Portal Were Not Processed

                                                                                                              Hi everyone, We want to bring to your attention a serious issue we’ve experienced with the Zoho support Help Portal. For more than a week, tickets submitted directly via the Help Portal were not being handled at all. At the same time no alert was posted
                                                                                                            • Unarchive tickets

                                                                                                              How can I manually unarchive tickets?
                                                                                                            • Optimize your Knowledge Base for enhanced accessibility by adding alt tags for images

                                                                                                              Let's learn why alt tags are crucial for your articles. You can add alternative tags (alt tags) and alternative text (alt text) to the images you share on your community forums or when embedding them in articles. Alt tags refer to the HTML attribute,
                                                                                                            • report showing assignment type

                                                                                                              Hi, We've created a number of workflows to allow us to auto assign tickets to agents based on keywords and other criteria. I'm struggling to create a report that would show me what is the percentage of tickets that are assigned automatically via workflows
                                                                                                            • Time Entry Notifications

                                                                                                              Hi All - I have support staff who place notes of their work in the time entry section of Zoho Desk. Is there a specific workflow or setting I need to enable to have the ticket holder updated via email when an entry is saved?
                                                                                                            • How to report 'Response violation' OR 'Resolution violation'

                                                                                                              Hi, I want to report on SLA Violation Type. I grouped my tickets on this column. It seems I only get 'Response and Resolution Violation' or 'Not Violated'. The former seems to be given to a ticket if only the Response Time was violated. I would expect
                                                                                                            • Should I Use DMARC?

                                                                                                              When I configure Zoho Mail's DMARC settings, it's mandatory to fill in the RUA and RUF (Aggregate notification email address*, Forensic notification email address*) addresses. When we enter an email address in these fields, we receive reports from the
                                                                                                            • Power of Automation :: Quick way to associate your Projects with Zoho CRM

                                                                                                              A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate complex tasks and
                                                                                                            • Formula field with IF statement based on picklist field and string output to copy/paste in multi-line field via function

                                                                                                              Hello there, I am working on a formula field based on a 3-item picklist field (i.e. *empty value*, 'Progress payment', 'Letter of credit'). Depending on the picked item, the formula field shall give a specific multi-line string (say 'XXX' in case of 'Progress
                                                                                                            • Unable to retrieve Contact_Name field contents using Web API in javascript function

                                                                                                              Hello, I've added a field in the Purchase Order form to select and associate a Sales Order (Orden_de_venta, lookup field). I've also created a client script to complete some fields from the Sales Order (and the Quote), when the user specifies the related
                                                                                                            • Restricting contact creation

                                                                                                              Hi all! I am looking to use Zoho Desk in a part of the business that takes end user enquiries. These are generally single interactions, and not linked to an account name. As Desk is Account centric, has anyone designed a way to manage these incoming emails
                                                                                                            • Import Holiday Calendars

                                                                                                              HI Zoho Is there anyway of importing an online calendar like https://www.calendarlabs.com into the business hours calendars, to speed up setup of holiday calendars. Also could we also request a feature where you can specify a Holiday as hours, i.e it could be that the company is on a 1/2 day due to a holiday or when it is Eid in the UAE and they are only allowed to work restricted hours so we need the calendar to be flexible to allow for this. Regards Jamie
                                                                                                            • Filtering Tickets based on Email headers

                                                                                                              We're starting to get a lot more junk coming into our Zoho Desk, which is then triggering unnecessary email alerts to agents. Once thing we could do to cut this junk in half, is to filter tickets based on email headers. Any email containing the `List-Unsubscribe`
                                                                                                            • Zoho Books - France

                                                                                                              L’équipe de Zoho France reçoit régulièrement des questions sur la conformité de ses applications de finances (Zoho Books/ Zoho Invoice) pour le marché français. Voici quelques points pour clarifier la question : Zoho Books est un logiciel de comptabilité
                                                                                                            • Feature Request: Conditional Field Mandatoriness Based on Display Status

                                                                                                              Hello Zoho Creator Team, I would like to suggest an enhancement to improve the flexibility of form validations. Currently, when we need a field to be mandatory only if it's displayed on the form, the only option is to: Set the field as not mandatory in
                                                                                                            • Im Stuck in an EDIT ONLY WITH WIZARD issue

                                                                                                              So I found Wizards to be a really helpful tool in minimizing the exposure of redundant, superfluous fields to staff that would never otherwise have to edit those fields. My issue is, that when the record (in this case a lead) is created with a wizard,
                                                                                                            • Data Migration Strategies for Moving to a Cloud Solution

                                                                                                              Hi everyone, I’ve been working on moving some of our critical systems, including CRM and project data, to a Zoho cloud solution, and one of the biggest challenges I’ve encountered is data migration. Transferring large volumes of data while keeping it
                                                                                                            • Bulk Moving Images into Folders in the Library

                                                                                                              I can't seem to select multiple images to move into a folder in order to clean up my image library and organize it. Instead, I have to move each individual image into the folder and sometimes it takes MULTIPLE tries to get it to go in there. Am I missing
                                                                                                            • Error 550 5.4.1

                                                                                                              I’ve tried sending an email to someone but keep receiving this back. Any help would be greatly appreciated 
                                                                                                            • Automatic Matching from Bank Statements / Feeds

                                                                                                              Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In these
                                                                                                            • Has Anyone successfully integrated Zoho and Sage Intact?

                                                                                                              Hey all, We’re evaluating Zoho One + Sage Intacct and I’m trying to connect with anyone who has actually implemented the two together.Specifically, I’d love to know: -- Which functions you kept in Zoho vs. Intacct (e.g., Product Catalog, AR/AP, invoicing,
                                                                                                            • Store "Sign in with Google/Microsoft/GitHub etc." details

                                                                                                              Quite often now, users are using a sign-in provider like Google or Microsoft to sign into various apps and services. It would be great if Vault could remember which providers you use for each website and sign you in with that provider instead of a username
                                                                                                            • Placing a condition before converting the LEAD

                                                                                                              Hi,  I need some assistance with Lead conversion. I need to place certain conditions before allowing the user to convert the lead.  For example: up until the certain status's doesn't equal "green" don't allow to convert lead.  I tried creating this using
                                                                                                            • Subform edits don't appear in parent record timeline?

                                                                                                              Is it possible to have subform edits (like add row/delete row) appear in the Timeline for parent records? A user can edit a record, only edit the subform, and it doesn't appear in the timeline. Is there a workaround or way that we can show when a user
                                                                                                            • How can I filter a field integration?

                                                                                                              Hi,  I have a field integration from CRM "Products" in a form, and I have three product Categories in CRM. I only need to see Products of a category. Thanks for you answers.
                                                                                                            • Adding image in HTML report page

                                                                                                              Hi, I want to know two things: 1. Can anyone advise how to add an image in HTML report. The tagged used is <img> but what path do I mention for the image to be added in the HTML report. 2. Also, I want to know if I am creating an application for the market
                                                                                                            • How to change view of HTML report based on device but always print in A4

                                                                                                              Hello everyone, I am aware that HTML report view can be configured to adjust according to the screen size like Laptop, Tablet and mobile using media queries. But my concern is no matter on which device the reports is opened when printed should always
                                                                                                            • Age Calculation

                                                                                                              I've attempted to calculate the age of someone based on their birthday input by using the formula field. It works but I don't want all those decimals on there. I then tried to use "set variable" after birthday input but I get a field type mismatch, long vs. floating. Any ideas would be wonderful.
                                                                                                            • Search on Custom Field

                                                                                                              We're working on an integration with the Zoho FSM API and are trying to retrieve companies based on a custom field we added to the Companies module. However, we can't find a way to filter or query records using custom fields through the API. We have a
                                                                                                            • in zoho creator Sales Returns form has sub form Line Items return quantity when i upate the or enter any values in the sub form that want to reflect in the Sales Order form item deail sub form field Q

                                                                                                              in zoho creator Sales Returns form has sub form Line Items return quantity when i upate the or enter any values in the sub form that want to reflect in the Sales Order form item deail sub form field Quantity Returned\ pls check the recording fetch_salesorder
                                                                                                            • Sendmail function / custom action?

                                                                                                              I've setup a function hoping to email various business departments the details of a record once all work in that record is complete so gone about setting up a custom action in such way that each record line on the report has a button to click. Question is how do I actually include data from that record in the email that is sent when the button is clicked? I had thought that since this were being sent per record the email would include the data which had been entered
                                                                                                            • API to post drafts for social media

                                                                                                              I we want to post draft posts to our zoho social account and then approve and schedule them within Zoho social. is this possible with for example: https://apis.zoho.com/social/v2/post TIA Jon
                                                                                                            • Integración Books para cumplir la ley Crea y Crece y Ley Antifraude (VeriFactu)

                                                                                                              Hola: En principio, en julio de 2025, entra en vigor la ley Crea y Crece y Ley Antifraude (VeriFactu). ¿Sabéis si Zoho va a cumplir con la ley para cumplir con la facturación electrónica conectada a Hacienda? Gracias
                                                                                                            • Canvas View in Zoho Recruit

                                                                                                              Is it possible or would it be possible to have the new 'Canvas View' in Zoho Recruit?
                                                                                                            • What impactful sales coaching techniques have you used to boost your team's performance?

                                                                                                              I'm curious about the real-world impact of sales coaching on team performance. What specific techniques or strategies have you found most effective in driving consistent improvement and growth in your sales team? Any success stories or lessons learned
                                                                                                            • Adding Taxes to paid consultations in Zoho Bookings

                                                                                                              I created a 'paid' consultation under Zoho Booking and integrated it with payment gateways for online/instant payment before a booking is done. How can I add 'taxes' to the price of consultation? I can add taxes to other Zoho apps (liks Books, Checkout,
                                                                                                            • Next Page