Ad-hoc survey requests are sent on a need basis as-and-when a specific contact becomes eligible to take the survey. These requests are triggered through API to Freshsurvey from the other system. These requests can be triggered to both Email and web-app embed collectors across all the survey frequencies (Transactional/ One-time/ Recurring).



How to configure an Ad-hoc trigger request:


  1. Once you activate the ‘Collector (Email/ Web App Embed)’, you will see a right slider with instructions to trigger the ad-hoc request.

  1. Alternatively, at any time you can click on ‘Show instructions’ against the collector to find the step-by-step instructions to configure ad hoc trigger requests via API (or webhook). 



  1. You will be able to trigger a survey request ad-hoc by making a POST request to the below callback URL with the request payload from any product viz. help desk, or order processing system. 


https://public-api.freshsurvey.io/public-api/v1/surveys/<survey_id>/triggers/ 

Note: <survey_id> in the Callback URL which be auto-populated in the instructions drawer. You can simply copy the URL.

  1. This request requires authentication. Please ensure to pass apiKey header with the API key value provided in the instruction screen. Alternatively, You can find the API key in Settings > Account info page as well.

  1. Now, Copy the JSON payload that you need to pass it along with the request for contact creation and triggering the survey.  

A few things to note here:

  • The “collector_ids” helps the system understand which collector Freshsurvey should use to trigger/ render the survey. This information is prepopulated in the “Show instruction” slider. 

  • It is necessary to pass on all the contact mandatory fields in the payload. Be default Freshsurvey system mandatory field is  “Email address” referred as “work_email” in the contact fields.  


Here is the Sample JSON payload:


{

  "collector_ids": [

    "SC-123"

  ],

  "contacts": [

    {

      "fields": {

        "work_email": "[email protected]",

        "first_name": "john",

        "last_name": "doe"

      }

    }

  ],

  "transaction_context": {

    "product_id_string": "123456",

    "order_id_string": "123456",

    "sample_number": 111

  }

}


Attribute

Description

Type

Values

collector_ids

Survey collector which you wish to trigger

string

Unique, auto-populated ID. 

contacts

All default and custom contact fields of the contact for which the survey needs to be triggered should be passed into the fields object.

object

You need to replace the contact field values like "John", "Smith", and "[email protected]",  found in the sample payload, with your static contact information or a dynamic placeholder value.


Default contact fields names:

  • first_name

  • last_name

  • work_email (Mandatory)

  • work_number

  • mobile_number

  • designation

  • address

  • city

  • state

  • country

  • zipcode

  • language

  • timezone

  • industry

  • company_name

  • company_website


Custom contact fields:

The field names of the custom contacts added in the Freshsurvey can be used here to collect them. The field names of the custom contact field can be found in Settings > Contact fields.


Note: 

  1. Make sure to pass all the ‘Required’ fields else the request will fail.

  2. we support only the below mentioned format for;

  • Date/time fields: We support only ISO format (yyyy-MM-dd'T'HH:mm:ss.SSSXXX). For example, 2022-10-31T01:30:00.000+05:00. 

  • Timezone: We support timezone only if it is passed in either 'Asia/Kolkata' or 'UTC+05:30' format. 

transaction_context

You can choose to pass additional transaction-related context along with the request which we will display along with the response collected. For eg., if you have configured the survey to trigger every time a support ticket gets resolved. You can pass on ticket-related context to Freshsurvey like Ticket ID, Agent name, etc. 

object

You can pass all the transaction context that needs to be captured by Freshsurvey along with the response. You need to pass the context key in the below format only.


"<transactional_property>_datatype"


If ticket_id is the transactional property that needs to be sent and if its datatype is a string. You need to pass it on as ticket_id_string. 


We support the following datatypes:  "string", "date", "number", "checkbox", "boolean", "text", "paragraph", "json"


Note: 

  1. Date/time fields: We support only ISO format (yyyy-MM-dd'T'HH:mm:ss.SSSXXX). For example, 2022-10-31T01:30:00.000+05:00. 

  2. A survey can have up to 100 transactional fields and of this only the first 20 transactional fields received across the collectors for any given survey will be filterable meaning only those 20 transactional fields will be visible in Response filters and can be used for response filtering. 








      6. If you are already a Freshworks customer and are using products like Freshdesk, Freshservice, Freshchat, etc, and want to trigger a survey we have pre-populated the sample payload with the respective placeholders. You can simply choose the product name you work with from the dropdown and copy the respective code. 

Note: As specificed in the Step 5, you can also customize the payload to suit your need.



Things to note: 

  1. For a one-time or recurring survey, if a contact is already part of the audience List or Segment that is associated with that collector. The contact would have got the trigger or survey rendered already and if an ad hoc request is sent for the same contact, we will send the survey again. So, we recommend you either remove the contact from the list or do not trigger ad hoc requests for such contact to avoid reaching the same contact twice for the survey. 

  2. If you trigger multiple ad-hoc requests for one-time or recurring surveys at any given point in time, we will merge all those requests and trigger only the latest request.