NPS-Net Promoter Score
N/A
Quick Guide
Subscription
The first step is subscribe to our API in the subscription
For the purpose of this tutorial, the BASIC plan subscription is enough to cover the most part of it. If you need a trial period on advanced feature, let us know in the comments area.
NPS Entities
The data is structured in a tree of entities as follows:
Survey
It is the document (JSON) containing customer answers to a template of questions. This is the lowest level of the structure and also carries information about customer interaction id, timestamp of interaction, template id and the answers. A survey belongs to a template.
Template
It is the document (JSON) containing the questions that customers will be presented to answer. There may be several templates with different questions to be presented to the customers. There are 2 basic types of templates: default and custom templates.
default template:
Holds a basic set of 3 questions (where the first is mandatory to exist)
Example:
{
"name": "myTemplateName",
"oid": "MYOR-52139735-20211201205330220090",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyCompany to your friends?",
"q2": "In a scale of 0-5, where 0 mean not satisfied at all and 5 means exceeded your expectations, how do you evaluate our services?",
"q3": "Leave us a message describing your experience with our product and services"
}
NOTE:
The text questions is free to be defined, but keeping in mind that the text of the first question MUST be the one that ask to the customer evaluate in a 0-10 scale the likely to recommend your company/brand/product/etc…
name: (str) A descriptive name (with no spaces or special characters)
oid: (str) Organization ID. When you identify a template with an oid, this template is part of an Organization collection of templates.(see: “Organization” topic)
system: (str) A label that can be used to identify the system or the channel through the customer used to submit the survey.
lang: (str) ENUM to indicate the template’s language. Default is “english”.
q1: (str) Question 1 and is mandatory. This is the question which the customer must reply with a NPS 0-10 scale value.
q2: (str) Question 2 and should be used to ask to the customer a numeric value to rate anything.
q3: (str) Question 3 and should be used to ask to the customer write down a text or comments to later evaluated (word cloud and/or sentiment analysis)
custom template:
Extends a default template. The 3 first set of questions are mandatory and you can extend at your free will for new fields.
Example:
{
"name": "myTemplateName",
"oid": "MYOR-52139735-20211201205330220090",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyCompany to your friends?",
"q2": "In a scale of 0-5, where 0 mean not satisfied at all and 5 means exceeded your expectations, how do you evaluate our services?",
"q3": "Leave us a message describing your experience with our product and services",
"q4": "How do you know about our company?",
"logistics": { "q1": "Do your product was delivery on schedule?"
"q2": "How long your product took to be delivered?"}
}
NOTE:
Despite being a custom template, it is mandatory to have the first question (q1) the one that ask to the customer evaluate in a 0-10 scale the likely to recommend your company/brand/product/etc… This will be the only question taken into account to calculate the NPS. if you need another custom model, please feel free to contact us in order to evaluate your needs
Organization
It is a way to identify / connect a collection of templates. It is a document (JSON) containing a name , an email and a status. When created, its ID can be used in templates creation to identify them as belonging to an organization.
{
"name": "Cleverthings",
"email": "engineer@clever.com",
"enabled": true
}
When it is created, you get an oid in order to use it in you templates if you need (see: “Templates”)
Summarizing:
One Organization can have one or more Templates, each template can have one or more Surveys.
Organization ---------> Templates ---------> Surveys
Creating our first NPS
Let’s consider a simple use case:
A webstore that sells products online and after checkout, customers are invited to evaluate the buying process. The webstore sells 2 types of products (product “A” and product “B”) and for each of them we want to evaluate the customer experience with different questions. At the management level, we want to have knowledge of each customer answer in detail, as well the NPS of each template individually and the overall NPS of the organization (which aggregate the two templates).
Create an Organization
First, we will create the organization “MyWebStore” invoking the endpoint Create Organization (/nps/organization/create) and passing the following payload in the body:
{
"name": "MyWebStore",
"email": "sales@mywebstore.com",
"enabled": true
}
After submitted, we got the Organization ID (oid) MYWE-4FBC6883-20211205032711644956:
{
"inserted":"MYWE-4FBC6883-20211205032711644956"
"acknowledged":true
}
Create Templates
Once we want to have 2 different templates, one for each product purchase, let’s create the first template "TemplateProductA"
invoking the endpoint Create NPS default template (/nps/template/create/default) and passing the following payload in the body:
{
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"lang": "english",
"system": "web",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?"
}
After submitted, we got the Template ID (tid) TEMP-1F58EB73
{
"inserted":"TEMP-1F58EB73"
"acknowledged":true
}
Then, we create the second template “TemplateProductB” invoking again the Create NPS default template passing the following payload:
{
"name": "TemplateProductB",
"oid": "MYWE-4FBC6883-20211205032711644956",
"lang": "english",
"system": "web",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Evaluate our prices from 0 (very expensive) to 5 (very cheap)",
"q3": "What you can say about our product line B?"
}
After submitted, we got the Template ID (tid) TEMP-5C1F92E3
{
"inserted":"TEMP-5C1F92E3"
"acknowledged":true
}
Submiting NPS Customer Surveys
Customers are faced with a small form in the webpage after checkout of products A and B, which present them the questions from templates A and B respectively. The webstore first need to invoke the endpoint Read NPS template (/nps/template/read/{tid}) passing a Template ID (tid) for each product. For instance: TEMP-1F58EB73 for product A and TEMP-5C1F92E3 for product B.
Doing so , we got the templates:
{
"_id":"TEMP-1F58EB73"
"name":"TemplateProductA"
"oid":"MYWE-4FBC6883-20211205032711644956"
"system":"web"
"lang":"english"
"q1":"Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?"
"q2":"Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)"
"q3":"Tell us about your purchase experience?"
"template_type":"default"
"create_date":"2021-12-05T03:46:29.937000"
}
and
{
"_id":"TEMP-5C1F92E3"
"name":"TemplateProductB"
"oid":"MYWE-4FBC6883-20211205032711644956"
"system":"web"
"lang":"english"
"q1":"Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?"
"q2":"Evaluate our prices from 0 (very expensive) to 5 (very cheap)"
"q3":"What you can say about our product line B?"
"template_type":"default"
"create_date":"2021-12-05T04:01:27.579000"
}
Those payloads are then received by webstore application which renders in the UI the 3 questions to the user. This part (rendering a form) is not provided by this API, but only feeding the data needed.
Notice here some important parts:
- All templates refers to belong to the same Organization (oid)
- Both templates are “default” types (with only 3 questions) automatically assigned
- There’s a timestamp of creation automatically assigned
Those templates then provides the questions that should be presented in the form of survey for customers to answer.
After responded, the webstore must send the surveys answers indicating the respective matching templates id.
To do this, is necessary to invoke the endpoint Submit a default survey passing a template id in the path (nps/survey/default/{tid}) and a JSON body with the answers as following:
For Product A
{
"client_id": "customerWeb123",
"a1": 9,
"a2": 3,
"a3": "Website with friendly user interface. Easy to find products"
}
We got the survey id (sid) 02946960:
{2 items
"inserted":"02946960"
"acknowledged":true
}
For Product B
{
"client_id": "customerWeb456",
"a1": 5,
"a2": 1,
"a3": "Product too expensive to its qualitye perceived and design is outdated"
}
We got the survey id (sid) E95F3FCF:
{
"inserted":"E95F3FCF"
"acknowledged":true
}
Many more surveys can be submitted from different customers about the same purchase processes of product A and B, and all the responses will be considered in the analysis of NPS for each template and overall for the entire organization.
Alternatively, surveys can be posted passing all parameters in the URL invoking “Submit default survey via url parameters” endpoint.
Example: (/nps/survey/default/TEMP-5C1F92E3?client_id=customerXpto&a1=9&a2=3&a3=The best product ever!)
Reading NPS Customer Surveys
Customers surveys can be read invoking “Read a survey” (/nps/survey/read/{sid}) endpoint passing the parameter Survey ID (sid), for instance 02946960 and E95F3FCF:
For product A:
[
0:{
"_id":"02946960"
"client_id":"customerWeb123"
"a1":9
"a2":3
"a3":"Website with friendly user interface. Easy to find products"
"template_type":"default"
"survey_date":"2021-12-05T04:22:29.287000"
"tid":"TEMP-1F58EB73"
"cx1":"promoter"
"cx2":"detractor"
"week_day":7
"day":5
"month":12
"year":2021
"hour":4
"minute":22
}
]
For product B:
[
0:{
"_id":"E95F3FCF"
"client_id":"customerWeb456"
"a1":5
"a2":1
"a3":"Product too expensive to its qualitye perceived and design is outdated"
"template_type":"default"
"survey_date":"2021-12-05T04:28:43.451000"
"tid":"TEMP-5C1F92E3"
"cx1":"detractor"
"cx2":"detractor"
"week_day":7
"day":5
"month":12
"year":2021
"hour":4
"minute":28
}
]
Notice important parts of these responses:
- Timestamp of when the survey was submitted
- The template ID each survey belongs to
- cx1 is the qualified evaluation of the 0-10 range NPS metric
- cx2 also aplies the same NPS metric evaluation, but just for convenience. There is no consideration of this parameter in the NPS calculation in template or organization reports. cx2 takes into account the numeric value of q2 (a2). If in your template q2 ask to rate out of a range 0-10, than the NPS evaluation (promoter, detractor, passive) is not relevant.
This method gives you an atomic view of each survey . To get a broader view of your customers surveys, you may want to see all those answers grouped by template or even by organization.
Reporting: NPS Organization
We can measure the NPS for an Organization within a delimited period of datetime. This can be done invoking “NPS Organization” endpoint passing Organization id (oid) and a start_date and end_date (/nps/report/organization/{oid}?start_date={sd}&end_date={ed}) for our organization MYWE-4FBC6883-20211205032711644956 from 2021-12-01T00:58:40 to 2021-12-09T23:58:40
As we saw earlier, an Organization is a collection of Templates.
In the output bellow we can see a global/combined NPS for all templates, and invidually NPS for each template.
{
"MYWE-4FBC6883-20211205032711644956": {
"promoters": 1,
"detractors": 1,
"passives": 0,
"nps": 0.0,
"start_date": "2021-12-01T00:58:40",
"end_date": "2021-12-09T23:58:40",
"templates": [
{
"TEMP-1F58EB73": {
"promoters": 1,
"detractors": 0,
"passives": 0,
"nps": 100.0,
"start_date": "2021-12-01T00:58:40",
"end_date": "2021-12-09T23:58:40",
"template": {
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?",
"template_type": "default",
"create_date": "2021-12-05T03:46:29.937000"
}
}
},
{
"TEMP-5C1F92E3": {
"promoters": 0,
"detractors": 1,
"passives": 0,
"nps": -100.0,
"start_date": "2021-12-01T00:58:40",
"end_date": "2021-12-09T23:58:40",
"template": {
"name": "TemplateProductB",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Evaluate our prices from 0 (very expensive) to 5 (very cheap)",
"q3": "What you can say about our product line B?",
"template_type": "default",
"create_date": "2021-12-05T04:01:27.579000"
}
}
}
]
}
}
Reporting: NPS Template
We can measure the NPS for a particular template within a delimited period of datetime. This can be done invoking “NPS Template” endpoint passing template id (tid) and a start_date and end_date (/nps/report/template/{tid}?start_date={sd}&end_date={ed}) for each template, for instance: TEMP-1F58EB73 and TEMP-5C1F92E3 from 2021-12-01T00:58:40 to 2021-12-09T23:58:40:
As we saw earlier, a Template is a collection of Survey answered by customers.
In the output bellow we can see a global NPS for each template.
{
"TEMP-1F58EB73": {
"promoters": 1,
"detractors": 0,
"passives": 0,
"nps": 100.0,
"start_date": "2021-12-01T00:58:40",
"end_date": "2021-12-09T23:58:40",
"template": {
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?",
"template_type": "default",
"create_date": "2021-12-05T03:46:29.937000"
}
}
}
{
"TEMP-5C1F92E3": {
"promoters": 0,
"detractors": 1,
"passives": 0,
"nps": -100.0,
"start_date": "2021-12-01T00:58:40",
"end_date": "2021-12-09T23:58:40",
"template": {
"name": "TemplateProductB",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Evaluate our prices from 0 (very expensive) to 5 (very cheap)",
"q3": "What you can say about our product line B?",
"template_type": "default",
"create_date": "2021-12-05T04:01:27.579000"
}
}
}
** Important notes here: **
- As long we have only 1 survey answer per each template above, the NPS is at extremes (-100 and 100). However, as soon we add more customer surveys, this values will be automatically updated each time we invoke the reporting endpoint.
- The result of this endpoint has 2 important sections: a.) Template identification and its summary NPS calculation, b.) Template details with questions presented to the customers that led to the answers considered in the NPS calculation.
Reporting: NPS Client
We can measure the NPS for a particular customer (client) within a delimited period of datetime. This can be done invoking “NPS Client” endpoint passing Client id (cid) and a start_date and end_date (/nps/report/client/{cid}?start_date={sd}&end_date={ed}) for each client, for instance: customerWeb123 and customerWeb456 from 2021-12-01T00:58:40 to 2021-12-09T23:58:40:
As we saw earlier, a Customer submit its survey to a given Template of questions.
In the output bellow we can see a global NPS for each client, and the details of each survey answer and the related template id (tid).
"customerWeb123": {
"promoters": 1,
"detractors": 0,
"passives": 0,
"nps": 100.0,
"survey_answers": [
{
"_id": "02946960",
"client_id": "customerWeb123",
"a1": 9,
"a2": 3,
"a3": "Website with friendly user interface. Easy to find products",
"template_type": "default",
"survey_date": "2021-12-05T04:22:29.287000",
"tid": "TEMP-1F58EB73",
"cx1": "promoter",
"cx2": "detractor",
"week_day": 7,
"day": 5,
"month": 12,
"year": 2021,
"hour": 4,
"minute": 22
}
]
}
}
{
"customerWeb456": {
"promoters": 0,
"detractors": 1,
"passives": 0,
"nps": -100.0,
"survey_answers": [
{
"_id": "E95F3FCF",
"client_id": "customerWeb456",
"a1": 5,
"a2": 1,
"a3": "Product too expensive to its qualitye perceived and design is outdated",
"template_type": "default",
"survey_date": "2021-12-05T04:28:43.451000",
"tid": "TEMP-5C1F92E3",
"cx1": "detractor",
"cx2": "detractor",
"week_day": 7,
"day": 5,
"month": 12,
"year": 2021,
"hour": 4,
"minute": 28
}
]
}
}
** Important note ** :
As we explained in the previous section “Reading NPS Customer Surveys” , cx2 also aplies the same textual NPS metric evaluation, but just for convenience and can be ignored if the numeric range scale to this question is not the same considered by NPS calculation (0-10). In the examples above, cx2 is rated as detractor (and is not considered in any NPS calculation) because the questions that led to this answers ask to the customers evaluate in a range from 0-5 a specific dimension of interest (ex: price, quality, etc).
Adding more surveys
Presumably in real cases scenarios we’ll have more than 1 customer survey answered by our customers, and several different evaluations of each one. To mimic this behavior, let’s insert a bunch of other surveys for each of one those templates in order to get a more realistic approach to NPS Calculation and Inspection in this exercise.
To do this, we will use a script to insert randomly 100 records, invoking Submit a default survey (/nps/survey/default/{tid})
After inserted, we can now check that templates TEMP-1F58EB73 and TEMP-5C1F92E3 has lot more customer surveys answers.
Now we can move to next part to inspect each one of them and get more insights.
Detail All Templates Surveys Answers
Sometimes may be useful to get a list of all answers and its respective templates details in one shot. To get this, you can invoke the endpoint Details all templates answers (/nps/report/surveys/template/{tid}) along with a given template id (tid).
A sample output for template TEMP-1F58EB73 is shown below:
{
"template": {
"_id": "TEMP-1F58EB73",
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?",
"template_type": "default",
"create_date": "2021-12-05T03:46:29.937000"
},
"total_survey_answers": 54,
"survey_answers": [
{
"_id": "02946960",
"client_id": "customerWeb123",
"a1": 9,
"a2": 3,
"a3": "Website with friendly user interface. Easy to find products",
"template_type": "default",
"survey_date": "2021-12-05T04:22:29.287000",
"tid": "TEMP-1F58EB73",
"cx1": "promoter",
"cx2": "detractor",
"week_day": 7,
"day": 5,
"month": 12,
"year": 2021,
"hour": 4,
"minute": 22
},
{
"_id": "CFDBD47A",
"client_id": "CLI-69cbb",
"a1": 7,
"a2": 5,
"a3": "I always use it, I mean I use it everyday ,cause",
"template_type": "default",
"survey_date": "2021-12-05T17:06:12.254000",
"tid": "TEMP-1F58EB73",
"cx1": "passive",
"cx2": "detractor",
"week_day": 7,
"day": 5,
"month": 12,
"year": 2021,
"hour": 17,
"minute": 6
},
{ ...}
]
}
````
Breaking it down, we got the template section where we can check template’s questions and details, such as: id, name, organization it belongs to, questions, type and when it was created:
"template": {
"_id": "TEMP-1F58EB73",
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?",
"template_type": "default",
"create_date": "2021-12-05T03:46:29.937000"
}
There are two more elements in the document root, where you can find how many surveys this template has and each survey answer in detail:
"total_survey_answers": 54,
"survey_answers": [ {
"_id": "02946960",
"client_id": "customerWeb123",
"a1": 9,
"a2": 3,
"a3": "Website with friendly user interface. Easy to find products",
"template_type": "default",
"survey_date": "2021-12-05T04:22:29.287000",
"tid": "TEMP-1F58EB73",
"cx1": "promoter",
"cx2": "detractor",
"week_day": 7,
"day": 5,
"month": 12,
"year": 2021,
"hour": 4,
"minute": 22
},
{
"_id": "CFDBD47A",
"client_id": "CLI-69cbb",
"a1": 7,
"a2": 5,
"a3": "I always use it, I mean I use it everyday ,cause",
"template_type": "default",
"survey_date": "2021-12-05T17:06:12.254000",
"tid": "TEMP-1F58EB73",
"cx1": "passive",
"cx2": "detractor",
"week_day": 7,
"day": 5,
"month": 12,
"year": 2021,
"hour": 17,
"minute": 6
},
{...}
]
Detail All Organization Surveys Answers
In a similar way, sometimes may be useful to get a list of all answers and its respective templates details in one shot for an entire Organization. To get this, you can invoke the endpoint Details all organization surveys (/nps/report/surveys/organization/{oid}) along with a given organization id (oid).
A sample output for organization MYWE-4FBC6883-20211205032711644956 is shown below:
{
"organization": {
"_id": "MYWE-4FBC6883-20211205032711644956",
"name": "MyWebStore",
"email": "sales@mywebstore.com",
"enabled": true,
"create_date": "2021-12-05T03:27:11.644000"
},
"total_templates": 2,
"total_survey_answers": 103,
"survey_answers": [
{
"template": {
"_id": "TEMP-1F58EB73",
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?",
"template_type": "default",
"create_date": "2021-12-05T03:46:29.937000"
},
"total_survey_answers": 54,
"survey_answers": [ {...},{...},...]
},
{
"template": {
"_id": "TEMP-5C1F92E3",
"name": "TemplateProductB",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Evaluate our prices from 0 (very expensive) to 5 (very cheap)",
"q3": "What you can say about our product line B?",
"template_type": "default",
"create_date": "2021-12-05T04:01:27.579000"
},
"total_survey_answers": 49,
"survey_answers": [ {...},{...},...]
}
Breaking it in parts, we have a first section where you’ll find all organization details and total templates it owns, as well the total number of answered surveys (103 for 2 templates)
{
"organization": {
"_id": "MYWE-4FBC6883-20211205032711644956",
"name": "MyWebStore",
"email": "sales@mywebstore.com",
"enabled": true,
"create_date": "2021-12-05T03:27:11.644000"
},
"total_templates": 2,
"total_survey_answers": 103
The remaining part is the detail of each template and their detailed answers (54 for template TEMP-1F58EB73, 49 for TEMP-5C1F92E3)
"survey_answers": [
{
"template": {
"_id": "TEMP-1F58EB73",
"name": "TemplateProductA",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Rate how easy was to buy in our website, ranging from 0 (very dificult) to 5 (very easy)",
"q3": "Tell us about your purchase experience?",
"template_type": "default",
"create_date": "2021-12-05T03:46:29.937000"
},
"total_survey_answers": 54,
"survey_answers": [ {...},{...},...]
{
"template": {
"_id": "TEMP-5C1F92E3",
"name": "TemplateProductB",
"oid": "MYWE-4FBC6883-20211205032711644956",
"system": "web",
"lang": "english",
"q1": "Using a 0-10 scale, how likely is it that you would recommend MyWebStore to your friends?",
"q2": "Evaluate our prices from 0 (very expensive) to 5 (very cheap)",
"q3": "What you can say about our product line B?",
"template_type": "default",
"create_date": "2021-12-05T04:01:27.579000"
},
"total_survey_answers": 49,
"survey_answers": [ {...},{...},...]
Conclusion
Beside the (almost) basic functionalities shown here, there are others features not covered in this quick guide that you can explore using the BASIC and other PAID features, such as:
- NPS Reporting
- Word Cloud
- Sentiment Analysis
New features may come in the next release or by suggestion if possible to implement in a reasonable effort for all plans.
Any doubt , problem or suggestion, please contact us !
Thank you !