The ad-hoc survey requests are API requests made for any contact to trigger the survey ad-hoc or on demand for the collector with any frequency be it one-time or recurring or even a transactional type. Additionally, for a transactional type survey collector, you will be able to trigger the survey whenever a transaction occurs like when a support ticket gets resolved, a customer purchases a product, etc. 


Configure ad-hoc/transactional trigger request:


  1. Once you activate the collector, Click on ‘Show instructions’. 


  1. On clicking ‘Show instructions’, you will find the instructions to configure ad hoc /transactional 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. 


Callback URL (POST):

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


Note: <survey_id> in the Callback URL will 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. Alternatively, You can find the API key in Settings > Account info.


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


Here is the Sample JSON payload:


{
  "collector_ids": [
    "SC-123"
  ],
  "contacts": [
    {
      "fields": {
        "work_email": "johndoe@example.com",
        "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 "john.smith@example.com",  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. 


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


For example, Let’s say you wish to trigger a CSAT survey to your contact every time a support ticket raised by them is resolved by an agent. All you have to do is go to Admin > Automations and create an automation rule saying “If Ticket status is Resolved, perform ‘Trigger webhook’ action”. You can simply copy and paste all required information as seen in the screenshot above and create the transactional triggers for the survey instantly. Similarly, you can configure for Freshservice and Freshchat as well with the help of Workflow automation.


Things to note: 

  1. For a one-time or a recurring survey, if a contact is already part of the audience in the List or a Segment that is associated with that collector and if an ad hoc request is sent for the same contact, we will send 2 surveys. So, we recommend you either remove the contact from the list or you do not trigger ad hoc request for such contact to avoid survey fatigue. 
  2. If you trigger multiple ad-hoc requests for one-time or recurring surveys at any given point of time, we will merge all those requests and trigger only the latest request. But, in the case of transactional surveys, we will honor all the trigger requests.