Trigger Invitations using Zoho Survey API

Trigger Invitations using Zoho Survey API

Overview 

Enabling the Zoho Survey API allows you to automatically distribute surveys via email to your contacts. Any application can use trigger-based email distribution to send email invitations when an event occurs.

Use Cases :

Here are some scenarios where the ZohoSurvey API Integration can be enabled:
  1. A customer buys a product from an ecommerce site and the seller wishes to send  a product feedback survey once the purchase has been delivered.
  2. A travel agency wishes to collect trip feedback from tourists once they return back can use the API integration.
  3. A hospital wishes to send a feedback survey to the patients after an appointment.
  4. To send a post-event survey to capture valuable feedbacks from attendees to get insights about the event.
  5. When a student completes a course in a learning platform, a survey can be sent to collect feedback about the course and the learning experience.
  6. To send an onboarding experience survey when an employee joins an organization.

Terminologies :

  1. OAuth- An industry-standard protocol that provides secure access to protected resources without giving away the user's password.
  2. Client - An application that sends requests to Zoho Survey to access the triggered invitations on behalf of the end-user.
  3. Client ID- A unique identifier you receive when you register your application with Zoho.
  4. Client Secret- A unique key generated when you register your application with Zoho. This must be kept confidential.
  5. Grant Token- A temporary token used to generate the Access and Refresh tokens. Generating an organization-specific grant token is a one-time process.
  6. Access Token- A token that is sent to the Zoho Survey API to access the triggered invitations of the user. The Access token provides secure and temporary access to Zoho Survey API .Each access token will be valid only for an hour and can be used only for the set of operations that are described in the scope.
  7. Refresh Token- A token that can be used to obtain new access tokens. This token has an unlimited lifetime until it is revoked by the end-user.
  8. API Rate Limit-The API rate limit is the maximum number of API calls that can be simultaneously active at any given point in time.

Pre-Requisites: 

  1. Valid Zoho Survey user credentials.
  2. Valid authentication token or OAuth to access Zoho Survey API.
  3. Should have configured the email distribution in the Zoho Survey portal.

How To: 

Enabling the API Trigger invitation begins with registering your client with the Zoho Developer Console.

Register your Application  

  1. Register your application with Zoho's Developer console in order to generate your Client ID and Client Secret.
  2. Once the Client ID and Client Secret are generated, generate organization-specific Grant Token   based on your client type using the scope "ZohoSurvey.invitation.CREATE". The Grant token is required only for specific clients like self clients and Server based applications.
  3. Copy the grant token that is generated. Learn More about generating the Client ID and Client Secret for various app types.
 

Generate Access Token and Refresh Token    

Next, using the Grant token, generate an access token and refresh token with your domain-specific Zoho Accounts URL.


The following are the various domains and their corresponding accounts URLs.
For SA(Saudi Arabia): https://accounts.zoho.sa

Note:
  1. For server based applications, send an authorization request with the access type parameter value as 'offline'. If the value is offline, you will receive a refresh token along with an access token for the first time you make the request. Once the access token expires, you can use the refresh token to regenerate them.
  2. Each access token is valid for only 1 hour and can only be used for the operations defined in the scope.
  3. To generate a new access token, use the refresh token. A refresh token does not expire. Use the refresh token to re-generate access tokens when they expire. 

 Creating Email Distribution 

  1. In the Zoho Survey portal, navigate to the Launch tab, then click Create Email.
 

  1. In the Send To section, choose Contacts based on triggers and click Next.



  1. Choose the frequency of triggers as One Time Invite or Recurring Invites. If you're choosing Recurring Invites, schedule the frequency of triggers.


 
  1. Click Create to receive an API Trigger URL. The API Info will be displayed on the success screen, and can be viewed any time to check the API details under Launch > Email > Triggered Invitations.



  1. Copy the request URL and configure the variables as shown below:
 
Method  POST
Header     Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
                       (key)                        (value)
Content-Typeapplication/json  

Request Body:

Request Body:

Parameter
Data type
Description
emailAddress*
string
Specify the email address of the contact
phoneNumber
string
Specify the phone number of the contact.
firstName
string
Specify the first name of the contact.
lastName
string
Specify the last name of the contact.
variableOne
string
You can add this variable field to collect additional data
variableTwo
string
You can add this variable field to collect additional data
variableThree
string
You can add this variable field to collect additional data
variableFour
string
You can add this variable field to collect additional data
variableFive
string
You can add this variable field to collect additional data
variableSix
string
You can add this variable field to collect additional data
* Required fields

Note
You can add multiple contacts per POST request.

Sample Request  

Refer to the Sample request below to use the curl command for executing the API:

-H "Authorization: Zoho-oauthtoken 1000.e4af2b6xxxxxxxxxxxxxbaaba.xa5xxxxxxxxxxxxxxxf"
-d "@contacts.json"
-X POST
In the request, "@contacts.json" contains the sample input data.
Sample Input  
{
"contactsList": [
{
"emailAddress": "bella@example.com",
"phoneNumber": "+1234567890",
"firstName": "bella",
"lastName": "steve",
"variableOne": "variable1",
"variableTwo": "variable2",
"variableThree": "variable3",
"variableFour": "variable4",
"variableFive": "variable5",
"variableSix": "variable6"
},
{
"emailAddress": "john@example.com",
"phoneNumber": "+1234567890",
"firstName": "John",
"lastName": "steve"
}
]
}

  HTTPS Status Codes

 
HTTP Status
Message
Explanation
200 OK
 
If you receive this status, it means the API trigger is successful.
530
ACCESS_RESTRICTED
The distribution is not in trigger state. Verify the API Request URL or create a new distribution with a trigger-based medium.
530
NEED_RECIPIENTS
The contact is empty or if it has an invalid email address.
400
INVALID_REQUEST_METHOD
You have specified an invalid HTTP method to access the API URL. Specify a valid request method.
401
OAUTH_SCOPE_MISMATCH
Client does not have the required scope. Create a new client with a valid scope.
530
DISTRIBUTION_DISABLED
The provided triggered invitation is disabled.
530
INVITATION_LIMIT_REACHED
You have exhausted the invitation count limit for the Trigger Expiry.
530
DAILY_EINVITE_LIMIT_REACHED
You have exhausted your daily invite limit.
530
EINVITE_BOUNCE_RATE_EXCEEDED
You have exhausted your account bounce rate limit.
530
EINVITE_COMPLAINT_RATE_EXCEEDED
You have exhausted your account complaint rate limit.
 

Points To Note 

  1. Revoking Refresh Token :You should use your domain-specific Zoho Accounts URL and send a revoke token request in order to revoke the refresh token. Learn more.
  2. Token Validity: There are limits regarding how many tokens can be stored and how many requests can be sent at a time. Learn more.
  3. The API limit on total requests for a distribution per minute is 60.




    Zoho CRM Training Programs

    Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

    Zoho CRM Training
      Redefine the way you work
      with Zoho Workplace

        Zoho DataPrep Personalized Demo

        If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

        Zoho CRM Training

          Create, share, and deliver

          beautiful slides from anywhere.

          Get Started Now


            Zoho Sign now offers specialized one-on-one training for both administrators and developers.

            BOOK A SESSION









                                      You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.




                                          Manage your brands on social media

                                            Zoho Desk Resources

                                            • Desk Community Learning Series


                                            • Digest


                                            • Functions


                                            • Meetups


                                            • Kbase


                                            • Resources


                                            • Glossary


                                            • Desk Marketplace


                                            • MVP Corner


                                            • Word of the Day


                                              Zoho Marketing Automation

                                                Zoho Sheet Resources

                                                 

                                                    Zoho Forms Resources


                                                      Secure your business
                                                      communication with Zoho Mail


                                                      Mail on the move with
                                                      Zoho Mail mobile application

                                                        Stay on top of your schedule
                                                        at all times


                                                        Carry your calendar with you
                                                        Anytime, anywhere




                                                              Zoho Sign Resources

                                                                Sign, Paperless!

                                                                Sign and send business documents on the go!

                                                                Get Started Now




                                                                        Zoho TeamInbox Resources



                                                                                Zoho DataPrep Resources



                                                                                  Zoho DataPrep Demo

                                                                                  Get a personalized demo or POC

                                                                                  REGISTER NOW


                                                                                    Design. Discuss. Deliver.

                                                                                    Create visually engaging stories with Zoho Show.

                                                                                    Get Started Now









                                                                                                        • Related Articles

                                                                                                        • Introduction to Zoho Survey

                                                                                                          Zoho Survey was launched to cater to the growing needs of the survey market. Whether you're a business person, a professor, an artist, or a college student, Zoho Survey helps you communicate with a diverse audience. You can now create surveys by ...
                                                                                                        • Create a Survey

                                                                                                          Welcome to Zoho Survey! Survey is an easy-to-use tool that helps you create surveys and questionnaires to collect various types of data on topics like customer satisfaction, healthcare, human resources, and education. You can create your survey using ...
                                                                                                        • Salesforce Integration

                                                                                                          The Zoho Survey-Salesforce integration empowers businesses to effortlessly sync survey responses, leads, and customer feedback directly into Salesforce. By bridging these platforms, users can leverage comprehensive customer insights gathered from ...
                                                                                                        • Trigger Emails

                                                                                                          Triggers are actions or workflows that you can create from within Zoho Survey. Zoho Survey currently supports three triggers, Trigger Emails, Trigger Functions, and Webhook. You can set up automated email notifications for every survey response or ...
                                                                                                        • Trigger Functions

                                                                                                          Zoho Survey is integrated with Deluge, our online scripting language, which can help you add functions to automatically perform actions when responses are submitted. Use Deluge and APIs to create connections and push data to third-party services or ...
                                                                                                          Wherever you are is as good as
                                                                                                          your workplace

                                                                                                            Resources

                                                                                                            Videos

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



                                                                                                            eBooks

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



                                                                                                            Webinars

                                                                                                            Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                                            CRM Tips

                                                                                                            Make the most of Zoho CRM with these useful tips.



                                                                                                              Zoho Show Resources