Customer Survey API Overview

Our customer survey API allows you to collect customer satisfaction in a very simple way by measuring the Net Promoter Score. This allows to automate the collection of customer feedback, normalize the received data and calculate satisfaction scores to track your performance.

Automation of feedback collection

Easily integrate feedback collection using our REST API in your key processes and customer interactions.

Normalization of data collection

Always send the same question for a defined process, interaction or team. Bad responses are automatically eliminated. Multiple languages are supported for the same question. Add segmentation (like tags) when sending the survey without revealing personal customer data (we don’t store any personal data).

Acting on your data

Reports can be generated through the API so that you can track your scores. Reports generation is fully dynamic and flexible, and can be generated from an survey level up to your company level.

Important note: the service is currently only available in Belgium via the SMS channel (SMS received by your customers from a Belgian short number). We will be adding new channels such as voice calls or email soon with a more international reach.

How to use the Promoter Survey API

Creating and managing surveys

1. Create one or more surveys

As a prerequisite you need at least one survey. Note that this is a configuration activity which should happen relatively rarely. You would only use it if you would like to track your customer satisfaction for a new service / product, a new team, or a new process. Use the POST /surveys endpoint to create a survey.

name and interactionType are 2 parameters intended to help you categorize your surveys. You can put anything in there as long as it makes sense for your organization.

The name parameter can give context to better identify what the survey is for: you may add a team name, a product name, the member of your team, or anything you wish that will help present meaningful reports.

The interactionType should indicate the kind of customer interaction on which you want to measure the satisfaction of your customers: sales inquiry, payment, service delivery, customer care, billing, etc. As an example of categorization, you could have:

• Name: support team / interactionType: service cancellation
• Name: support team / interactionType: technical issue
• Name: waffles / interactionType: general
• Name: biscuits / interactionType: general

Creating more than one survey using name / interactionType is also a good way to personalize your questions with contextual information. For example you can personalize the question with the product name: “On a scale from 0-10 , how likely are you to recommend our waffles to a friend or colleague?”

Request example:

curl -X POST 'https://api.enco.io/survey/1.0.0/surveys' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
--data-raw '{
    "name":"waffles",
    "interactionType":"general",
    "questions": [
        {
            "body":"On a scale from 0-10 , how likely are you to recommend our waffles to a friend or colleague?",
            "language": "en-GB"
        }
    ]
}'

Response body example:

{
  "id": 8,
  "name": "waffles",
  "interactionType": "general",
  "questions": [
    {
      "id": 13,
      "body": "On a scale from 0-10 , how likely are you to recommend our waffles to a friend or colleague?",
      "language": "en-GB"
    }
  ]
}

2. Get and delete a list of your surveys

Once you have created at least one survey you can get a list of your survey as described below.

Request example:

curl -X GET 'https://api.enco.io/survey/1.0.0/surveys' -H 'Content-Type: application/json' -H 'Authorization: Bearer <token>'

Response body example:

[
  {
    "id": 8,
    "name": "waffles",
    "interactionType": "general",
    "questions": [
      {
        "id": 13,
        "body": " On a scale from 0-10 , how likely are you to recommend our waffles to a friend or colleague?",
        "language": " en-GB "
      },
      {
        "id": 11,
        "body": " Quelle est la probabilité, sur une échelle de 0-10, que vous recommandiez nos gauffres à un ami ou un collègue? ",
        "language": "FR"
      }
    ]
  },
  {
    "id": 7,
    "name": "biscuits",
    "interactionType": "general",
    "questions": [
      {
        "id": 12,
        "body": " On a scale from 0-10 , how likely are you to recommend our biscuits to a friend or colleague?",
        "language": " en-GB "
      },
      {
        "id": 10,
        "body": " Quelle est la probabilité, sur une échelle de 0-10, que vous recommandiez nos biscuits à un ami ou un collègue? ",
        "language": "FR"
      }
    ]
  },
]

To delete a survey you should use the request below. Be very careful when deleting a survey as this will delete all the data (responses and scores) for that survey.

Request example:

curl -X DELETE 'https://api.enco.io/survey/1.0.0/surveys/{id}' -H 'Content-Type: application/json' -H 'Authorization: Bearer <token>'

3. Add questions in other languages

You can add questions to your existing surveys by using the request below. This is essentially here to support multiple languages, but we are not strict on the language definition so you can use it in whatever way you wish as long as it is supported by the ISO 15924 specifications. For example you may want to implement a different “tone of voice” for the same language and send different questions based on your segmentation.

Request example:

curl -X POST 'https://api.enco.io/survey/1.0.0/surveys/{id}/question' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
--data-raw '{
    "body":"Hoe was jou ervaring met ons support team? Stuur ons je score tussen 0 en 10 door te antwoorden op dit bericht",
    "language": "nl-BE"
}'

Sending surveys

Probably the most used service will be sending the survey. This is also what will affect your invoice. We do have some basic rules in place (for example you can’t send a survey to the same person in a short amount of time), but you will have to implement your own logic on when and which context to send the survey. You will have to map each of your process or product to the right survey and send the survey appropriately. Importantly, if you have a CRM system you can also use customer segmentation when sending the survey, which allows you to filter your scores based on those segments. The channel parameter is mandatory and allows you to define how to send the survey. Currently “SMS” and “VOICE” are the only supported channels.

Request example:

curl -X POST 'https://api.enco.io/survey/1.0.0/surveys/{id}/send' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
--data-raw '{
    "requests": [
            {
                "channel": "SMS",
                "segments": [
                        "male",
                        "customer"
                    ],
                "destination": "+32472306705",
                "referenceId": "my-customer-reference",
                "language": "en-GB"
            }
        ]
}'

Reporting on surveys

You can generate 2 types of reports. A global one which will aggregate the data of all your surveys, or a report per survey (e.g. per interaction or team). You have 2 separate endpoints for these 2 types of reports:

• /surveys/{id}/report
• /report

The parameters allow you to generate the report for your preferred period (for example you may generate a quarterly report and a monthly report) and filter on segments or channel.

The segment array corresponds to the list of tags or filters you want to apply. You must have used the segment parameter when sending the surveys in order to be able to filter on segments. The segmentMode parameter can be “ALL” (== segment1 AND segment2 AND…) or “ANY” ( == segment1 OR segment2 OR…).

In the response body, you will get a recap of your request, the NPS score and some response statistics. The NPS score is a number between -100 and 100. We also provide the number of promoters and detractors (absolute values) to give a finer view on the response split. Statistics are provided purely on the response so that you can evaluate the response rate and how well your surveys are performing. We may increase the scope of these reports in the future (adding more data insights, methods to measure satisfaction, or mathematical functions).

Request example:

curl -X GET 'https://api.enco.io/survey/1.0.0/surveys/{id}/report?endDate=2020-03-31T12%3A12%3A15.982%2B01%3A00&channel=SMS&segmentMode=ANY&segments=hxsyqosx,ifywjutr&startDate=2019-11-01T12%3A12%3A15.982%2B01%3A00' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>'

Response body example:

{
  "date": "2020-02-07T16:54:42.179",
  "from": "2019-11-01T12:12:15.982",
  "to": "2020-03-31T12:12:15.982",
  "segments": [],
  "segmentMode": "ALL",
  "nps": {
    "promoters": 1,
    "detractors": 0,
    "score": 100
  },
  "responseStatistics": {
    "totalRequests": 1,
    "totalResponses": 1,
    "goodResponses": 1,
    "badResponses": 0,
    "failed": 0
  }
}