Create Unique Survey URLs Using API Endpoint
Overview
The API Endpoint feature generates a unique survey URL for each respondent by accepting contact details through an API call. This lets external systems trigger URL generation automatically at the right moment, without manual intervention. The generated URL can then be distributed through your own communication channels.
For example, a hospital has a patient management system that handles thousands of appointments daily. The moment an appointment is marked complete, the hospital's system calls the Zoho Survey unique survey URL generation API endpoint with that patient's details and API returns a unique survey URL. The hospital sends it to the patient via internal tools.
Use Cases
Here are some scenarios where the Zoho Survey API Integration can be enabled:
- Send a product feedback survey automatically after a purchase is delivered on an ecommerce platform.
- A travel agency can use the API to automatically send trip feedback surveys to customers after they return.
- A hospital wishes to send a feedback survey to the patients after an appointment.
- Send post-event surveys to capture feedback from attendees and gain insights about the event.
- Trigger a course feedback survey automatically when a student completes a course on a learning platform.
- Send an onboarding experience survey automatically when a new employee joins the 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 active simultaneously at any given point in time.
Prerequisites:
- Valid Zoho Survey user credentials.
- Valid authentication token or OAuth to access Zoho Survey API.
- Existing 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, use the Grant token to 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, and can be used to re-generate access tokens when they expire.
API Trigger URL
- Once you select the Unique URL collector, click Continue.
- The API Info will be displayed on the screen as shown below.
- 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 was 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.
Access your files securely from anywhere
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:
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
New to Zoho Writer?
Create. Review. Publish.
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?
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
Create Unique Survey URLs Using CSV File Upload
Overview Upload a CSV file containing respondent details to generate a unique survey URL for each respondent. Share these URLs directly with respondents to ensure each person accesses the survey through their own unique URL. How to create unique ...Generate Unique URLs
Generate Unique URLs By generating unique survey URLs tailored to individual respondents, you can send targeted surveys to obtain more reliable and accurate survey results. Unique survey URLs provide privacy for both you and your respondents, so you ...Trigger SMS Invitations using Zoho Survey API
Trigger SMS Invitations Triggers are events that cause a certain action to happen when a pre-defined event occurs. With Zoho Survey's SMS triggers, users can send survey forms as trigger invitations. Users can send SMS invitations using the Zoho ...Create Brand URLs for Your Survey
Overview Create professional, brand-aligned survey URLs with Zoho Survey's White Label feature. Instead of sharing a generic Zoho-branded link, host your surveys on your own custom subdomain like survey.yourcompany.com to build trust and reinforce ...Create White Label URLs for Your Survey
Overview Take full ownership of your survey experience by creating white label URLs with Zoho Survey. Replace the default Zoho-branded link with your own custom subdomain such as survey.yourcompany.com thereby ensuring every touchpoint reflects your ...
New to Zoho LandingPage?
Zoho LandingPage Resources