TABLE OF CONTENTS



Overview

Freshsurvey is a free NPS survey tool that allows companies to build and publish NPS surveys for their customers via Email, Web-App, and Email embeds.  Freshsurvey, companies can collect NPS survey scores and get actionable insights, with easy-to-read reports and graphs.


Freshsurvey's APIs belong to the Representational State Transfer (REST) category. They allow you to perform 'RESTful' operations such as reading, modifying, adding, or deleting of data.



What API commands are used by Freshsurvey?

Freshsurvey APIs are plain JSON over HTTP and use the following HTTP verbs:

 

COMMAND

PURPOSE

POST

Create an object

GET

Fetch one or more objects

PATCH

Update an object

DELETE

Remove an object

Note: All API requests should hit the secured endpoint, that is, only HTTPS



Rate Limit

The number of API calls per hour is 1000



Policies

Freshsurvey APIs are classified into either production or beta APIs. A production API is one that has been made generally available for public use and is stable. A beta API is one that is still in development or is for internal or limited use and whose stability cannot be guaranteed. Beta APIs may be removed or modified at any time without advance notice. The following policies apply to production APIs only.



Deprecation Policy

The current version of production-level APIs is v1. When a new version of APIs is made generally available (not beta), the older version will be deprecated and will cease to function after six months. Once an API is removed, any request to it will result in a 404 error.



Breaking Change Policy

Changes that do not break an API, such as adding a new attribute can be made at any time. Changes that break a production-level API such as removing attributes or making major changes to the API’s behavior will only be done with advance notice of 60 days. However, there may be rare occasions where we are forced to make breaking changes without advance notice due to legal, performance, or security reasons.



Authentication

Authentication is done over API Key using 'apiKey' as key and Freshsurvey accounts API Key as value to authenticate the request.

curl --location --request GET 'https://public-api.freshsurvey.io/public-api/v1/' \
--header 'apiKey: xxx'

For example, if your API Key is 'abcdefghij1234567890', the curl command to use is:

curl --location --request GET 'https://public-api.freshsurvey.io/public-api/v1/contacts/?per_page=1&page=3' \
--header 'apiKey: abcdefghij1234567890'

Where can I find my API key?

  1. Login to your account

  2. Go to Settings > Account info

  3. Show API Key > Copy



Contacts


   

Attribute

Data Type

Type

Description

id

String

Mandatory

Contact id

work_email

String

Mandatory


first_name

String

Optional


last_name

String

Optional


work_number

String

Optional


mobile_number

String

Optional


company_name

String

Optional


company_website

String

Optional


industry

String

Optional


language

String

Optional


timezone

String

Optional

Timezone in either 'Asia/Kolkata' or 'UTC+05:30' format.

address

String

Optional


city

String

Optional


state

String

Optional


zipcode

String

Optional


country

String

Optional


blocked
Boolean

Optional


unsubscribed
Boolean

Optional


fields
JSON

Optional

JSON object containing custom contact fields. 

Note: Ensure to add the field name of the custom contact field as configured in Freshsurvey. The field name of the custom contact fields can be found in Settings > Contact fields.
created_at
Datetime

Optional

Datetime in ISO format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')
updated_atDatetime

Optional

Datetime in ISO format (yyyy-MM-dd'T'HH:mm:ss.SSS'Z')



Get all Contacts

GET: contacts/

Pagination: 

To scroll through the pages, add the parameter page to the query string. The page number starts with 1.

https://public-api.freshsurvey.io/public-api/v1/contacts/?page=3

By default, the number of objects returned per page is 100. This can be adjusted by adding the per_page parameter to the query string. The maximum number of objects that can be retrieved per page is 100. Invalid values and values greater than 100 will result in an error.

https://public-api.freshsurvey.io/public-api/v1/contacts/?per_page=10

The per_page and page parameters can also be used together. The following example will retrieve the contacts from 11 to 20.

https://public-api.freshsurvey.io/public-api/v1/contacts/?per_page=10&page=2

The 'meta' object in the response will hold the page information.

"meta": {
        "total_records_count": 1,
        "total_page_count": 1,
        "page_number": 1,
        "page_size": 100,
        "has_next_page": false,
        "has_previous_page": false
}

Response: List of contacts objects along with pagination information in meta object

{
    "contacts": [
        {
            "id": "1600796391446913011",
            "address": "Perungudi",
            "city": "Chennai",
            "country": "India",
            "first_name": "John",
            "last_name": "Doe",
            "mobile_number": "+918455584555",
            "state": "Tamil Nadu",
            "zipcode": "226010",
            "work_email": "john.doe@example.com",
            "work_number": "+918455584555",
            "created_at": "2022-12-08T10:16:15.736+00:00",
            "updated_at": "2022-12-08T12:54:13.229+00:00",
            "fields": {
                "custom_field_date": "2022-12-26T18:30:00Z",
                "custom_field_number": 123
            },
            "timezone": "Africa/Abidjan",
            "company_name": "Acme Inc",
            "company_website": "acmeinc.com",
            "language": "English",
            "industry": "Saas",
            "blocked": false,
            "unsubscribed": false
        }
    ],
    "meta": {
        "total_records_count": 1,
        "total_page_count": 1,
        "page_number": 1,
        "page_size": 100,
        "has_next_page": false,
        "has_previous_page": false
    }
}

Get a Contact by ID

GET: contacts/<contact_id>/


Response: Contact object

{
    "id": "1600796391446913011",
    "address": "Perungudi",
    "city": "Chennai",
    "country": "India",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+918455584555",
    "state": "Tamil Nadu",
    "zipcode": "226010",
    "work_email": "john.doe@example.com",
    "work_number": "+918455584555",
    "created_at": "2022-12-08T10:16:15.736+00:00",
    "updated_at": "2022-12-08T12:54:13.229+00:00",
    "fields": {
        "custom_field_date": "2022-12-26T18:30:00Z",
        "custom_field_number": 123
    },
    "timezone": "Africa/Abidjan",
    "company_name": "Acme Inc",
    "company_website": "acmeinc.com",
    "language": "English",
    "industry": "Saas",
    "blocked": false,
    "unsubscribed": false
}

Create a Contact

POST: contacts/

Request:

{
    "first_name": "John",
    "last_name": "Doe",
    "work_email": "john.doe@example.com"
}

Response: Newly created contact object

{
    "id": "1600796391446913011",
    "address": "Perungudi",
    "city": "Chennai",
    "country": "India",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+918455584555",
    "state": "Tamil Nadu",
    "zipcode": "226010",
    "work_email": "john.doe@example.com",
    "work_number": "+918455584555",
    "created_at": "2022-12-08T10:16:15.736+00:00",
    "updated_at": "2022-12-08T12:54:13.229+00:00",
    "fields": {
        "custom_field_date": "2022-12-26T18:30:00Z",
        "custom_field_number": 123
    },
    "timezone": "Africa/Abidjan",
    "company_name": "Acme Inc",
    "company_website": "acmeinc.com",
    "language": "English",
    "industry": "Saas",
    "blocked": false,
    "unsubscribed": false
}

Update a Contact by ID

PATCH: contacts/<contact_id>/


Request:

{
    "first_name": "John",
    "last_name": "Doe",
    "work_email": "john.doe@example.com"
}

Response: Updated contact object

{
    "id": "1600796391446913011",
    "address": "Perungudi",
    "city": "Chennai",
    "country": "India",
    "first_name": "John",
    "last_name": "Doe",
    "mobile_number": "+918455584555",
    "state": "Tamil Nadu",
    "zipcode": "226010",
    "work_email": "john.doe@example.com",
    "work_number": "+918455584555",
    "created_at": "2022-12-08T10:16:15.736+00:00",
    "updated_at": "2022-12-08T12:54:13.229+00:00",
    "fields": {
        "custom_field_date": "2022-12-26T18:30:00Z",
        "custom_field_number": 123
    },
    "timezone": "Africa/Abidjan",
    "company_name": "Acme Inc",
    "company_website": "acmeinc.com",
    "language": "English",
    "industry": "Saas",
    "blocked": false,
    "unsubscribed": false
}

Delete a Contact by ID

DELETE: contacts/<contact_id>/


Response: HTTP Status: 200 OK


Delete a Contact by Email

DELETE: contacts/<emailId>/


Response: HTTP Status: 200 OK


Ad-hoc / Transactional survey triggers


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



Attribute

Description

DataType

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. 



Create an ad-hoc / Transactional trigger request


POST:

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


Note: <survey_id> in the Callback URL should be replaced with the actual Survey ID of the survey which needs to be triggered for the contact. You can get the survey ID from the survey builder URL (abc.freshsurvey.io/app/survey/<survey_id>) or you can copy the callback URL directly from the 'Show instructions' drawer in the Collector list page. 


Request: 

{
  "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
  }
}

Response: HTTP Status: 200 OK