API document for Unique link generation
SurveySensum is a SAAS application, using the application anyone can create multiple surveys. These surveys can be shared to the customers through multiple channels like WhatsApp, Email, SMS. Once customers receive the survey, they click on the survey link (survey link which is shared via different channels), once user fills the survey on web application the response is captured SurveySensum platform. All the responses and the reporting can be viewed in SurveySensum reporting module. Below is the flow when user is manually sharing the survey form the platform.
Feedback collection flow:
Need of API integration:
User logged in
New feature launched
In these use cases SurveySensum provides REST api to communicate with the share module in SurveySensum platform to share the survey programmatically without manual interventions.
Prerequisites for API integrations:
Access token for authentication
Login to your SurveySensum account and go to your Account Settings.
On the settings page, go to Integration and Apps, Created Apps and then click 'Create Your App'
Enter the app name and a short description of your app and click on Create New App.
Once you create an app, an Access token will be visible on the screen with all permissions.
You can change permissions if you want to. But make sure to re-generate your Access token to apply those new permissions.
Contact properties codes: Each customer of your organization is identified in SurveSensum as a contact, in the api payload property code is required. Your customer may have information like name, email, phone number, city info, store id, region etc. Developers can ask the business user which user info they require in the survey response for further analysis. For knowing the codes you can go to SurveySensum platform-> Contacts-> Contact Properties , in the contact properties grid there is a column named “code”, in this field you can know the code for each property
Api Specs:
Request Method: Post
Request API URL: {{baseUrl}}/v2/
Request Headers:
Authorization: Bearer {token}
Content-type: application/json
Note: Token can be generated by logging in to SurveySensum platform-> Setting-> Integrations & Apps-> Created Apps, here you can create a new app for getting an Auth token
Json payload:
{
"contactInfo": [
{
"key": "vz_c_cusId",
"value": "cus1"
}
],
"metadata": [
{
"key": "Metadata prop descriptor code",
"value": "Metadata value"
}
]
}
Here's a breakdown of all the fields in the JSON payload:
contactInfo (Array of key-value pairs):
Purpose: This section contains contact-related information that helps personalize the survey link.
Structure: Each entry consists of:
"key": The name of the contact property.
"value": The actual value assigned to that contact property.
Example Explanation:
"contactInfo": [{
"key": "vz_c_cusId",
value": "cus1"
} ]
"vz_c_cusId" is a custom property representing the customer ID.
"cus1" is the value, meaning this survey link is being generated for customer with ID "cus1".
metadata (Array of key-value pairs):
Purpose: This section holds additional contextual data related to the survey.
Structure: Each entry consists of:
"key": A descriptor that identifies the metadata property.
"value": The actual metadata value.
Example Explanation:
"metadata": [{
"key": "Metadata prop descriptor code",
"value": "Metadata value"}]
"Metadata prop descriptor code" represents a custom metadata field (e.g., "transactionId", "productCategory").
"Metadata value" is the actual value assigned to this metadata field.
Api Response types:
if successful execution of api :
_________________________________
{
"statusCode": 200,
"result": [
"https://cx.surveysensum.com/5aB9BA9s"
],
"etag": null,
"errors": [],
"message": "success",
"corelationId": null
}
--------------------------------------------------------------------------------
if No contact properties provided:
____________________________________
{
"statusCode": 400,
"result": null,
"etag": null,
"errors": [],
"message": "Invalid/empty contact info",
"corelationId": null
}
--------------------------------------------------------------------------------------
if metaData key not exits :
___________________________________
{
"statusCode": 400,
"result": null,
"etag": null,
"errors": [],
"message": "invalid metadata",
"corelationId": null
}
--------------------------------------------------------------------------------------
if Contact is Duplicate(request for link generation for same contact within throttle days):
_________________________
{
"statusCode": 400,
"result": null,
"etag": null,
"errors": [],
"message": "One or more errors occurred. (Contact is duplicate)",
"corelationId": null
}
--------------------------------------------------------------------------------------------------
eration api from OPENAPI.txt
Use Case Example:
If you're sending a survey after a customer makes a purchase or logs into your system, you might populate these fields as follows:
{"contactInfo": [
{
"key": "customerId",
"value": "12345"
},
{
"key": "customerEmail",
"value": "user@example.com"
}
],
"metadata": [
{
"key": "transactionId",
"value": "txn_98765"
},
{
"key": "productCategory",
"value": "Electronics"
}
]
}
"customerId": "12345" links the survey to a specific customer.
"customerEmail": "user@example.com" allows personalized survey communication. "transactionId": "txn_98765" ties the survey to a specific transaction.
"productCategory": "Electronics" helps analyze feedback per category.
Example Curl Request: (Specific for generating survey link in BrowerStack’s Net Promoter Score Survey)
curl -X POST "{{baseUrl}}/v2/Share/shareSurvey/link?surveyGuid=de547eec-6b36-4ce1-90ab-8e411beaf985" -H "accept: text/plain" -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImIzYmJiNTA3YjZhMTRmMTcwYzU5MjZhMTBmODgwNDIyIiwidHlwIjoiSldUIn0.eyJuYmYiOjE3Mzg4Mzc4MzQsImV4cCI6MTc3MDM3MzgzNCwiaXNzIjoiaHR0cHM6Ly9wcm9kLWluLW1pY3JvLnN1cnZleXNlbnN1bS5jb20vc3RzIiwiYXVkIjpbImh0dHBzOi8vcHJvZC1pbi1taWNyby5zdXJ2ZXlzZW5zdW0uY29tL3N0cy9yZXNvdXJjZXMiLCJ2el9vcGVuX2FwaSJdLCJjbGllbnRfaWQiOiJmYTE2MmI3OS1lYWE4LTQxNTUtOTE4NC1jNWMxOWUzZDU1N2EiLCJzdWIiOiI4M2JjNjA1OS1lMmU0LTExZWYtYjhhMS0wMmE0YTY0NzNkMTEiLCJhdXRoX3RpbWUiOjE3Mzg4Mzc4MzMsImlkcCI6ImxvY2FsIiwiSXNQYW5lbEFsbG93ZWQiOiJGYWxzZSIsInN1YnNjcmlwdGlvbkd1aWQiOiI4N2NjOTJmZC1lMmU0LTExZWYtYjhhMS0wMmE0YTY0NzNkMTEiLCJ1c2VyR3VpZCI6IjgzYmM2MDU5LWUyZTQtMTFlZi1iOGExLTAyYTRhNjQ3M2QxMSIsInVzZXJJZCI6InJhaHVsYzI5QGdtYWlsLmNvbSIsIkZ1bGx5TWFuYWdlZFVzZXIiOiJmYWxzZSIsIkFnZW50VXNlciI6ImZhbHNlIiwiZm9yWmFwcGVyIjoiZmFsc2UiLCJzdWJJZCI6IjYxMDEiLCJ1c2VyU3RhdHVzIjoiNCIsIlBlcm1pc3Npb24iOlsiY3JlYXRlX2NvbnRhY3RfbGlzdHMiLCJ2aWV3X2NvbnRhY3RfbGlzdHMiLCJ1cGRhdGVfY29udGFjdF9saXN0cyIsImRlbGV0ZV9jb250YWN0X2xpc3RzIiwiY3JlYXRlX2NvbnRhY3QiLCJ2aWV3X2NvbnRhY3QiLCJ1cGRhdGVfY29udGFjdCIsImRlbGV0ZV9jb250YWN0IiwiY3JlYXRlX3N1cnZleXMiLCJ2aWV3X3N1cnZleXMiLCJ1cGRhdGVfc3VydmV5IiwiZGVsZXRlX3N1cnZleSIsInZpZXdfd2ViaG9va3MiLCJjcmVhdGVfd2ViaG9va3MiLCJ1cGRhdGVfd2ViaG9va3MiLCJkZWxldGVfd2ViaG9va3MiLCJjcmVhdGVfc2hhcmVzIiwidmlld19zaGFyZXMiLCJkZWxldGVfc2hhcmVzIiwidmlld19lbWFpbF90ZW1wbGF0ZXMiLCJ2aWV3X3Jlc3BvbnNlcyJdLCJzY29wZSI6WyJvcGVuaWQiLCJwcm9maWxlIiwibWFuYWdlX2NvbnRhY3RfbGlzdHMiLCJtYW5hZ2VfY29udGFjdHMiLCJtYW5hZ2Vfc3VydmV5cyIsIm1hbmFnZV93ZWJob29rcyIsInN1cnZleV9zaGFyZSIsInZpZXdfY29udGFjdF9saXN0cyIsInZpZXdfY29udGFjdHMiLCJ2aWV3X2VtYWlsX3RlbXBsYXRlcyIsInZpZXdfcmVzcG9uc2VzIiwidmlld19zdXJ2ZXlzIiwidmlld193ZWJob29rcyIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJwd2QiXSwiUm9sZXMiOlsiQWRtaW4iXX0.kJOU-NWmrp6yXsmOBmTrjnw18ZeiSWttoP9yP6ayUKC9VUSj0huIZqPyQY4D--M8tQZ8UF_JjwM31LLiUiBS1b0CNCDj58cSBqIkPzuD1geIwjQOxFNf6r6cjQ12gC0Of_C_sfcQqOqtj1l-4rQ6ziP4Q-uzZidpxkTKG90G3QXDPolEWYxX-fHJxucuY6C40QWF-83zmiVYigzwHGnm4kxe7ZtZ5McRYfQsoVWukRuvmx9p4rz5NfPDFz05JDfEPuEJpkAHMSgtX3cKHO8Q01xYLJcrCdTxJnBMv3Pn2ES7pIUOIDhnumT1K2yWDGLd6zTrUGJNTwOxfei4OJsImg" -H "Content-Type: application/json-patch+json" -d "{\"contactInfo\":[{\"key\":\"vz_c_email\",\"value\":\"email1@email.com\"}],\"metadata\":[{\"key\":\"transactionId\",\"value\":\"t1\"}]}"
Related Articles
How to create unique trackable links for surveys sent via external email/sms services
This feature will help you to track respondents while using external email/sms provider by generating unique links for each responder. You will need to upload the data in contacts section before using this feature. Let's suppose you already have a ...How to get a Survey Link in Salesforce via API call
Use - Case: When you want to send surveys created on SurveySensum via Salesforce, you have to configure this integration. Flow of Integration - Event happens in Salesforce, like a ticket gets closed. Immediately a request is sent to SurveySensum, ...API document for Sharing the survey via WhatsApp, SMS, Email
What is SurveySensum Platform: SurveySensum is a SAAS application, using the application anyone can create multiple surveys. These surveys can be shared to the customers through multiple channels like WhatsApp, Email, SMS. Once customers receive the ...Share Survey using Anonymous Link and on Social Media
Share Survey using Anonymous Link After creating your survey, your survey is ready to be shared! Start collecting anonymous responses for your survey. Let us see how we can share the survey via the anonymous link. You will be able to view the ...How to integrate with third-party applications using SurveySensum API's
Use SurveySensum application for using open API's to integrate with third-party applications SurveySensum API helps you to integrate with your own application ecosystems such as CRM, HRM, and Helpdesk applications. It frees you from the ...