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

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:

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:

curl "https://survey.zoho.com/api/v1/external-private/portals/113436589/departments/soCNLR/surveys/123430000050422385/collectors/123430000050422419/distributions/123430000050460139/email/sendinvitation"

-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.