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:
- 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.
- A travel agency wishes to collect trip feedback from tourists once they return back can use the API integration.
- A hospital wishes to send a feedback survey to the patients after an appointment.
- To send a post-event survey to capture valuable feedbacks from attendees to get insights about the event.
- 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.
- To send an onboarding experience survey when an employee joins an organization.
Terminologies :
- OAuth- An industry-standard protocol that provides secure access to protected resources without giving away the user's password.
- Client - An application that sends requests to Zoho Survey to access the triggered invitations on behalf of the end-user.
- Client ID- A unique identifier you receive when you register your application with Zoho.
- Client Secret- A unique key generated when you register your application with Zoho. This must be kept confidential.
- Grant Token- A temporary token used to generate the Access and Refresh tokens. Generating an organization-specific grant token is a one-time process.
- 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.
- 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.
- 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:
- Valid Zoho Survey user credentials.
- Valid authentication token or OAuth to access Zoho Survey API.
- 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
- Register your application with Zoho's Developer console in order to generate your Client ID and Client Secret.
- 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.
- 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 US: https://accounts.zoho.com
For AU: https://accounts.zoho.com.au
For EU: https://accounts.zoho.eu
For IN: https://accounts.zoho.in
For CN: https://accounts.zoho.com.cn
For JP: https://accounts.zoho.jp
For CA(Canada): https://accounts.zohocloud.ca
For SA(Saudi Arabia): https://accounts.zoho.sa
Note:
- 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.
- Each access token is valid for only 1 hour and can only be used for the operations defined in the scope.
- 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
- In the Zoho Survey portal, navigate to the Launch tab, then click Create Email.
- In the Send To section, choose Contacts based on triggers and click Next.
- Choose the frequency of triggers as One Time Invite or Recurring Invites. If you're choosing Recurring Invites, schedule the frequency of triggers.
- 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.
- Copy the request URL and configure the variables as shown below:
Method POST
Header Authorization: Zoho-oauthtoken e4af2b6xxxxxxxxxxxxxbaaba
(key) (value)
Content-Type: application/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
- 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.
- Token Validity: There are limits regarding how many tokens can be stored and how many requests can be sent at a time. Learn more.
- 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 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 Workerly Home
- Forums
- Connect With Us:
- Zoho Recruit Home
- Forums
- Connect With Us:
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
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.
New to Zoho Survey?
Zoho Sheet Resources
Zoho Forms Resources
New to Zoho Sign?
Zoho Sign Resources
Sign, Paperless!
New to Zoho TeamInbox?
Zoho TeamInbox Resources
New to Zoho ZeptoMail?
Zoho DataPrep Resources
Design. Discuss. Deliver.
New to Zoho Workerly?
New to Zoho Recruit?
New to Zoho CRM?
New to Zoho Projects?
New to Zoho Sprints?
New to Zoho Assist?
New to Bigin?
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 ...
New to Zoho LandingPage?
Zoho LandingPage Resources