Retently API
API ¶
Retently NPS API (v2) endpoints
Get customers ¶
Get customers
GET/api/v2/nps/customers{?page,limit,sort}
Example URI
string
(optional) Example: email=john@example.comFind a customer by the email address;
- page
integer
(optional) Example: 1The current page number. Default 1;
- limit
integer
(optional) Example: 20The items limit. Default 20;
- sort
string
(optional) Example: 'createdDate'The sort option. Use ‘-’ for DESC. Default ‘-createdDate’;
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"subscribers": [
{
"email": "john@example.com",
"id": "5a9d595701c85b38114b5a1",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"companyId": "60444db01eeeb6bf89799999",
"tags": [
"foo",
"baz",
],
"createdDate": "2019-07-28T04:33:13.217Z",
"properties": [
{
"label" : "Subscription name",
"name" : "subscription_name",
"type" : "text",
"value" : "Professional plan"
},
{
"label" : "Register date",
"name" : "register_date",
"type" : "date",
"value" : "2019-06-22T00:00:00.000Z"
}
]
},
],
"page": 1,
"pages": 10,
"limit": 20,
"sort": "-createdDate",
"total": 1000
}
}
Get customer by ID ¶
Get customer by ID
GET/api/v2/nps/customers/{customerId}
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"subscribers": [
{
"email": "john@example.com",
"id": "5a9d595701c85b38114b5a1",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"companyId": "60444db01eeeb6bf89799999",
"tags": [
"foo",
"baz",
],
"createdDate": "2019-07-28T04:33:13.217Z",
"properties": [
{
"label" : "Subscription name",
"name" : "subscription_name",
"type" : "text",
"value" : "Professional plan"
},
{
"label" : "Register date",
"name" : "register_date",
"type" : "date",
"value" : "2019-06-22T00:00:00.000Z"
}
]
},
],
"page": 1,
"pages": 1,
"limit": 1,
"sort": "-createdDate",
"total": 1
}
}
400
Headers
Content-Type: application/json
Body
{
"code": 400,
"message": "Validation failed",
"error": "ValidationError: \"value\" must only contain hexadecimal characters"
}
{
"code": 400,
"message": "Validation failed",
"error": "ValidationError: \"value\" length must be 24 characters long"
}
401
Headers
Content-Type: application/json
Body
{
"message": "Account not found.",
"code": 401,
"error": null
}
404
Headers
Content-Type: application/json
Body
{
"message": "Customer not found.",
"code": 404,
"error": null
}
Get companies ¶
Get companies
GET/api/v2/companies{?page,limit,sort}
Example URI
- page
integer
(optional) Example: 1The current page number. Default 1;
- limit
integer
(optional) Example: 20The items limit. Default 20;
- sort
string
(optional) Example: 'createdDate'Sort items. Use -createdDate for results in descending order.
Default: -createdDate
Sort options
Use “-” to pull results in descending order. Example: sort=-companyName
- createdDate
- domain
- companyName
- industryName
- contactsCount
- cxMetrics.NPS
- cxMetrics.CSAT
- cxMetrics.CES
- cxMetrics.STAR
Headers
Content-Type: application/json
Authorization: api_key={{your_api_key}}
200
Headers
Content-Type: application/json
Body
{
"code": 200,
"message": "Success.",
"data": {
"total": 3792,
"page": 1,
"limit": 20,
"sort": "-createdDate",
"companies": [
{
"id": "60444db01eeeb6bf89799999",
"createdDate": "2021-05-25T01:06:56.070Z",
"domain": "acme.com",
"companyName": "ACME",
"industryName": "E-commerce",
"tags": ["SMB", "example"],
"cxMetrics": {
"NPS": 71,
"CSAT": 53,
"CES": 22,
"STAR": null
},
"contactsCount": 195
},
],
}
}
400
Headers
Content-Type: application/json
Body
{
"code": 400,
"success": false,
"message": "Validation failed",
"error": "ValidationError: child \"page\" fails because [\"page\" must be a number]"
}
{
"code": 400,
"success": false,
"message": "Validation failed",
"error": "ValidationError: child \"limit\" fails because [\"limit\" must be a number]"
}
{
"code": 400,
"success": false,
"message": "Validation failed",
"error": "ValidationError: child \"sort\" fails because [\"sort\" must be one of [-createdDate, createdDate, -domain, domain, -companyName, companyName, -companyIndustry, companyIndustry, -contactsCount, contactsCount, -cxMetrics.NPS, cxMetrics.NPS, -cxMetrics.CSAT, cxMetrics.CSAT, -cxMetrics.CES, cxMetrics.CES, -cxMetrics.STAR, cxMetrics.STAR]]"
}
401
Headers
Content-Type: application/json
Body
{
"message": "Account not found",
"code": 401,
"data": null
}
{
"message": "Missing authorization key (api_key).",
"code": 401,
"data": null
}
Get company by id ¶
Get company
GET/api/v2/companies/{companyId|domain}
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{your_api_key}}
200
Headers
Content-Type: application/json
Body
{
"code": 200,
"message": "Success.",
"data": {
"id": "60444db01eeeb6bf89799999",
"createdDate": "2021-05-25T01:06:56.070Z",
"domain": "acme.com",
"companyName": "ACME",
"industryName": "E-commerce",
"tags": ["SMB", "example"],
"cxMetrics": {
"NPS": 71,
"CSAT": 53,
"CES": 22,
"STAR": null
},
"contactsCount": 195
}
}
401
Headers
Content-Type: application/json
Body
{
"message": "Account not found",
"code": 401,
"data": null
}
{
"message": "Missing authorization key (api_key).",
"code": 401,
"data": null
}
404
Headers
Content-Type: application/json
Body
{
"message": "Company record not found",
"code": 404
}
Get reports ¶
Get reports
GET/api/v2/reports/
Example URI
- Campaign ID
string
(optional):Pass the campaign ID to get the reports for a specific campaign. If no campaign ID is passed, then the Response will return data for all campaigns in the account.
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"code": 200,
"message": "Success.",
"data": [
{
"campaignId": "5f1ec45y27b8313876299999",
"trend": [
{
"day" : "2022-12-01",
"promoters" : 292,
"passives" : 194,
"detractors" : 25,
"total" : 511,
"score" : 52
},
{
"day" : "2022-12-02",
"promoters" : 292,
"passives" : 194,
"detractors" : 26,
"total" : 512,
"score" : 52
}
],
"last": {
"promoters" : 292,
"passives" : 194,
"detractors" : 24,
"total" : 512,
"score" : 52
},
"deliveryStats": {
"totalCount" : 2500,
"opened" : 800,
"responded" : 512,
"optedOut" : 0,
"isBounced" : 0
},
"questionsStats": [
{
"uuid" : "djxpv6to-p1n2-z9zl-1q71",
"title" : "Additional CSAT rating question",
"isStarred" : true,
"position" : 1,
"isOnMain" : true,
"metricsType" : "CSAT",
"stats" : {
"last": {
"day" : "2022-12-02",
"promoters" : 0,
"passives" : 0,
"detractors" : 1,
"responded" : 1,
"opened" : 1,
"skipped" : 0,
"total" : 1,
"scoreSum" : 1,
"score" : 1
},
"first": {
"day" : "2022-12-01",
"promoters" : 0,
"passives" : 0,
"detractors" : 1,
"responded" : 1,
"opened" : 1,
"skipped" : 0,
"total" : 1,
"scoreSum" : 1,
"score" : 1
}
}
}
]
}
]
}
Get latest score ¶
Get latest score
GET
/api/v2/{metric}/score
You can get the last score based on the survey metric. In the link replace {metric} with: nps,
star, csat, or ces. You can pull the score only for one metric at a time.
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"nps": 39,
"promoters": 62,
"passives": 15,
"detractors": 23,
"promotersCount": 8,
"passivesCount": 2,
"detractorsCount": 3,
"totalResponses": 13
}
}
401
Headers
Content-Type: application/json
Body
{
"message": "Account not found",
"code": 401,
"data": null
}
Get feedback ¶
Get feedback
GET/api/v2/feedback{?page,limit,sort,startDate,endDate}
Example URI
string
(optional) Example: john@example.comSearch responses by a customer’s email address;
- customerId
string
(optional) Example: customerId=5f1faaa4b4e2e4963e41893bSearch responses by a customer’s Retently ID;
- page
string
(optional) Example: 1The current page number. Default 1;
- limit
string
(optional) Example: 20The items limit. Default 20;
- sort
string
(optional) Example: 'createdDate'The sort option. Use ‘-createdDate’ for results in descending order.
Default ‘-createdDate’;- startDate
string
(optional) Example: '1514764800'UNIX timestamp;
- endDate
string
(optional) Example: '1526556971'UNIX timestamp;
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"responses": [
{
"id": "5f1faaa4b4e2e4963e41893b",
"customerId": "5ebc15b0cb0d12fd815c5cda",
"email": "john@example.com",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"companyId": "60444db01eeeb6bf89799999",
"jobTitle": "Marketing",
"country": "USA",
"state": "California",
"city": "San Francisco",
"tags": [
"foo",
"baz"
],
"customProps": [
{
"name" : "subscription",
"type" : "string",
"value" : "Professional"
},
{
"name" : "signed_up",
"type" : "date",
"value" : "2020-05-22T00:00:00.000Z"
}
],
"campaignName": "CSAT regular email campaign",
"campaignId": "60d983411991aad3dc2da064",
"createdDate": "2018-03-27T09:45:41.697Z",
"score": 5,
"comment": "I love everything about your product.",
"checkbox": true,
"additionalQuestions": [
{
"type" : "RATING",
"questionText" : "How likely are you to recommend our company to a friend or colleague?",
"metricsType" : "NPS",
"answer" : 10
},
{
"type" : "MULTIPLE_OPTIONS",
"questionText" : "What is the main reason for your score?",
"answer" : "Support"
}
],
"feedbackTags": [
"product",
"customer support"
],
"feedbackTopics": [
{
"name" : "Usability",
"sentiment" : "positive"
},
{
"name" : "Onboarding",
"sentiment" : "neutral"
},
{
"name" : "Pricing",
"sentiment" : "positive"
}
],
"feedbackTagsNew": [
"Product 1",
"Order status",
"Case number"
],
"notes": [
{
"author" : "Ann Doe",
"content" : "I have followed up with John and we've scheduled a demo call to showcase our new features",
"metricsType" : "NPS",
"date" : "2020-06-28T04:35:15.482Z"
}
],
"status": "",
"assigned": "Ann Doe",
"ratingCategory": "Positive",
"resolved": true,
"channel": "email",
"metricsType": "CSAT",
"isBogus": false
}
],
"page": 1,
"pages": 101,
"limit": 10,
"total": 1007
}
}
Get feedback by id ¶
Get feedback by id
GET/api/v2/feedback/{feedbackId|campaignId}
Example URI
- feedbackId
string
Example: '5a9d595701c85b37224ab2d0'
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"responses": [
{
"id": "5f1faaa4b4e2e4963e41893b",
"customerId": "5ebc15b0cb0d12fd811e4hgw",
"email": "john@example.com",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"companyId": "60444db01eeeb6bf89799999",
"jobTitle": "Marketing",
"country": "USA",
"state": "California",
"city": "San Francisco",
"tags": [
"foo",
"baz"
],
"customProps": [
{
"name" : "subscription",
"type" : "string",
"value" : "Professional"
},
{
"name" : "signed_up",
"type" : "date",
"value" : "2020-05-22T00:00:00.000Z"
}
],
"campaignName": "CSAT regular email campaign",
"campaignId": "60d983411991aad3dc4rv145",
"createdDate": "2018-03-27T09:45:41.697Z",
"score": 5,
"comment": "I love everything about your product.",
"checkbox": true,
"additionalQuestions": [
{
"type" : "RATING",
"questionText" : "How likely are you to recommend our company to a friend or colleague?",
"metricsType" : "NPS",
"answer" : 10
},
{
"type" : "MULTIPLE_OPTIONS",
"questionText" : "What is the main reason for your score?",
"answer" : "Support"
}
],
"feedbackTags": [
"product",
"customer support"
],
"feedbackTopics": [
{
"name" : "Usability",
"sentiment" : "positive"
},
{
"name" : "Onboarding",
"sentiment" : "neutral"
},
{
"name" : "Pricing",
"sentiment" : "positive"
}
],
"feedbackTagsNew": [
"Product 1",
"Order status",
"Case number"
],
"notes": [
{
"author" : "Ann Doe",
"content" : "I have followed up with John and we've scheduled a demo call to showcase our new features",
"metricsType" : "NPS",
"date" : "2020-06-28T04:35:15.482Z"
}
],
"status": "",
"assigned": "Ann Doe",
"ratingCategory": "Positive",
"resolved": true,
"channel": "email",
"metricsType": "CSAT",
"isBogus": false
}
],
"page": 1,
"pages": 101,
"limit": 10,
"total": 1007
}
}
400
Headers
Content-Type: application/json
Body
{
"code": 400,
"message": "An error occurred",
"error": Error: Argument passed in must be a single String of 12 bytes or a string of 24 hex characters
}
401
Headers
Content-Type: application/json
Body
{
"message": "Account not found",
"code": 401,
"data": null
}
404
Headers
Content-Type: application/json
Body
{
"message": "Feedback record not found.",
"code": 404,
"data": null
}
Get responses (Deprecated) ¶
Get responses
GET/api/v2/nps/customers/response{?page,limit,sort,startDate,endDate}
Example URI
- page
string
(optional) Example: 1The current page number. Default 1;
- limit
string
(optional) Example: 20The items limit. Default 20;
- sort
string
(optional) Example: 'createdDate'The sort option. Use ‘-’ for DESC. Default ‘-createdDate’;
- startDate
string
(optional) Example: '1514764800'UNIX timestamp;
- endDate
string
(optional) Example: '1526556971'UNIX timestamp;
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"responses": [
{
"email": "tombrown@example.com",
"firstName": "Tom",
"lastName": "Brown",
"companyName": "ACME",
"tags": [],
"createdDate": "2018-03-27T09:45:41.697Z",
"score": 10,
"comment": "",
"feedbackTags": []
},
{
"email": "johnsmith@example.com",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"tags": [
"csv"
],
"createdDate": "2018-03-27T09:37:43.072Z",
"score": 10,
"comment": "",
"feedbackTags": []
}
],
"page": 1,
"pages": 1,
"limit": 2,
"total": 2,
"startDate": "1514764800",
"endDate": "1526556971"
}
}
Get outbox ¶
GET OUTBOX
GET/api/v2/nps/outbox{?page,
limit}
Example URI
string
(optional) Example: email=john@example.comFind a customer’s outbox records by email address;
- page
string
(optional) Example: 1The current page number. Default 1;
- limit
string
(optional) Example: 50The items limit. Default 50;
- sort
string
(optional) Example: 'surveyCreatedDate'The sort option. Use ‘-surveyCreatedDate’ for results in descending order; Default ‘-surveyCreatedDate’;
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"surveys": [
{
"email": "john@example.com",
"customerId": "5ebc15b0cb0d12fd811e4hgw",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"companyId": "60444db01eeeb6bf89799999",
"personTags": "[]",
"sentDate": "2019-09-13T11:51:31.295Z",
"channel": "email",
"campaign": "Regular email NPS campaign",
"campaignId": "60d983411991aad3dc4rv145",
"surveyTemplateId": "60588921dabc1c6b6dg12419",
"subject": "How likely are you to recommend ACME to your friends?",
"sentBy": "manual",
"status": "RESPONDED",
"detailedStatus": {
"isOpened": true,
"openedDate": "2019-09-13T11:51:48.805Z",
"isResponded": true,
"respondedDate": "2019-09-13T11:51:48.805Z",
"hasFeedback": true,
"isOptedOut": false,
"isBounced": false
},
},
{
"email": "john@example.com",
"customerId": "5ebc15b0cb0d12fd811e4hgw",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"companyId": "60444db01eeeb6bf89799999",
"personTags": "[]",
"sentDate": "2019-09-13T11:51:31.295Z",
"channel": "email",
"campaign": "Regular email NPS campaign",
"campaignId": "60d983411991aad3dc4rv145",
"surveyTemplateId": "60588921dabc1c6b6dg12419",
"subject": "How likely are you to recommend ACME to your friends?",
"sentBy": "autoreply",
"status": "OPENED",
"detailedStatus": {
"isOpened": true,
"openedDate": "2019-09-13T11:51:48.805Z",
"isResponded": false,
"respondedDate": "",
"hasFeedback": false,
"isOptedOut": false,
"isBounced": false
},
"additionalRecipients": [
{
"email": "ann@example.com",
"type": "cc",
"mandrillMessageId": "3ec992d239754081bca1f9ad1572hf93",
},
{
"email": "dan@example.com",
"type": "bcc",
"mandrillMessageId": "3ec992d239754081bca1f9ad1572h332",
}
],
"mandrillMessageId": "3ec992d239754081bca1f9ad1572hf71"
}
],
"page": 1,
"pages": 1,
"limit": 2,
"sort": "-surveyCreatedDate",
"total": 2,
}
}
Get templates ¶
Get templates
GET/api/v2/templates
Example URI
Included in response:
- list with templates (except deleted templates)
- template id
- template name
- template channel
- template metric
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"code": 200,
"message": "Success.",
"templates": [
{
"id": "628765bf8743956",
"name": "Default NPS in-app template",
"channel": "inapp",
"metric": "STAR"
}
]
}
401
Headers
Content-Type: application/json
Body
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication Required."
}
Get templates (Deprecated) ¶
Get templates
GET/api/v2/nps/templates
Example URI
Note:
Please use the new endpoint: https://app.retently.com/api/v2/templates.
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
[
{
"id": "5a9cff9e48c0809113087557",
"value": "DRUPAL template"
},
{
"id": "5a9cf2ba48c0809113087506",
"value": "HEXAGON template"
}
]
GET CAMPAIGNS ¶
Get campaigns
GET/api/v2/campaigns
Example URI
Note:
- list with campaigns (except deleted campaigns)
- campaign id
- campaign status
- campaign name
- assigned template id
- campaign metric
- campaign channel
- campaign type
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
{
"code": 200,
"message": "Success.",
"campaigns":
[
{
"id": "62729a9d76fa98be",
"name": "NPS transactional email campaign",
"isActive": true,
"templateId": "627276f4997e",
"metric": "NPS",
"type": "transactional",
"channel": "email"
}
]
}
401
Headers
Content-Type: application/json
Body
{
"statusCode": 401,
"error": "Unauthorized",
"message": "Authentication Required."
}
GET ACTIVE TRANSACTIONAL CAMPAIGNS (Deprecated) ¶
Get active transactional campaigns
GET/api/v2/nps/campaigns
Example URI
Note:
Please use the new endpoint: https://app.retently.com/api/v2/campaigns.
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
200
Headers
Content-Type: application/json
Body
[
{
"id": "5a9d595701c85b37224ab2d0",
"value": "Transactional NPS campaign"
}
]
404
Headers
Content-Type: application/json
Body
{
"code": 404,
"success": false,
"message": "No Transactional NPS campaign(s) found."
}
Create or update customers ¶
Create or update customers
POST/api/v2/nps/customers
Maximum number of customers per request should not exceed 1,000.
Parameters
- subscribers: (required, array) - An array of customers;
- email: johnsmith@example.com (required, string) - Email address;
- first_name: John (optional, string) - First name;
- last_name: Smith (optional, string) - Last name;
- company: ACME (optional, string) - Company name;
- tags (optional, array) - An array of tags. Example: [“foo”, “bar”, “baz”];
- properties (optional, array) - An array of properties.
Manage customer properties
- To create a new customer property, you can include it in the customer’s object in your
request body, and give it a value. The property will be created (if it doesn’t exist
already) and assigned to the customer in Retently. When adding a property you will have
to pass the following parameters:
- “label”: This is the name of the property and how it will be displayed in Retently;
- “type”: There are 5 types of properties (string, date, integer, collection, and boolean);
- “value”: Add the value that will be stored in the property.
- To update customers' values in their properties, you can add the customer in the request and list the property with the updated value. If a customer already has older properties (that are missing from your request), they will be ignored and will not be updated, removed, or overwritten.
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"subscribers": [
{
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar"
],
"properties": [
{
"label" : "Subscription",
"type" : "string",
"value" : "Free trial"
},
{
"label" : "Signup date",
"type" : "date",
"value" : "12/31/2019"
},
{
"label" : "Subscriptions count",
"type" : "integer",
"value" : 1
},
{
"label" : "Features included",
"type" : "collection",
"value" : "campaigns, integrations, messenger"
},
{
"label" : "Subscribed",
"type" : "boolean",
"value" : true
}
]
}
]
}
200
Headers
Content-Type: application/json
Body
{
"message": "Request successfully sent.",
"code": 200,
"data": {
"subscribers": [
{
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo",
"bar",
"baz",
],
"createdDate": "2020-02-04T06:19:29.335Z",
"properties": [
{
"label" : "Subscription",
"name" : "subscription",
"type" : "string",
"value" : "Free trial",
},
]
}
}
"page": 1,
"pages": 10,
"limit": 20,
"sort": "-createdDate",
"total": 400,
}
SEND TRANSACTIONAL SURVEY ¶
Send transactional survey
POST/api/v2/nps/audience/survey
Parameters
-
campaign: (required, string) - The campaign ID where your customers will be surveyed;
-
subscribers: (required, array) - An array of objects that may contain 1 or up to 100 customers per request. Each customer object may include the following parameters:
- email: (required, string) - A variable with the email address of the customer;
- first_name: (optional, string) - A variable with the first name of the customer;
- last_name: (optional, string) - A variable with the last name of the customer;
- company: (optional, string) - A variable with the company name of the customer;
- tags (optional, array) - Any data passed in the array, will be imported as tags along with the customer. Example: [“foo”, “bar”, “baz”];
- properties (optional, array) - An array of objects which include customer properties.
Manage customer properties
-
To create a new customer property, you can include it in the customer’s object in your request body, and give it a value. The property will be created (if it doesn’t exist already) and assigned to the customer in Retently. When adding a property you will have to pass the following parameters:
- label: This is the name of the property and how it will be displayed in Retently;
- type: There are 5 types of properties (string, date, integer, collection, and boolean);
- value: Add the value that will be stored in the property.
-
To update customers' values in their properties, you can add the customer in the request and list the property with the updated value. If a customer already has older properties (that are missing from your request), they will be ignored and will not be updated, removed, or overwritten.
Note:
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"campaign": "5a9d595701c85b37224ab2d0",
"subscribers": [
{
"email": "john.smith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"foo","bar","baz"
],
"properties": [
{
"label" : "Subscription",
"type" : "string",
"value" : "Free trial"
},
{
"label" : "Signup date",
"type" : "date",
"value" : "12/31/2019"
},
{
"label" : "Subscriptions count",
"type" : "integer",
"value" : 1
},
{
"label" : "Features included",
"type" : "collection",
"value" : "campaigns, integrations, messenger"
},
{
"label" : "Subscribed",
"type" : "boolean",
"value" : true
}
]
}
]
}
200
Headers
Content-Type: application/json
Body
{
"success": true,
"code": 200,
"message": "Success.",
"status": "queued"
}
400
Headers
Content-Type: application/json
Body
{
"success": false,
"status": "error",
"code": 400,
"message": "Campaign 5a9d595701c85b37224ab2d0 is not transactional",
}
Body
{
"success": false,
"status": "error",
"code": 400,
"message": "Validation Error: Invalid email addresses",
"status": "error",
"data": [
{
"status": "fail",
"email": "john.smith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": ["foo", "bar", "baz"],
"reason": "\"email\" - Invalid email address",
}
]
}
401
Headers
Content-Type: application/json
Body
{
"message": Invalid API key.,
"code": 401,
"data": null,
}
403
Headers
Content-Type: application/json
Body
{
"success": false,
"status": "error",
"code": 403,
"message": "Campaign 5a9d595701c85b37224ab2d0 is not active.",
}
404
Headers
Content-Type: application/json
Body
{
"success": false,
"status": "error",
"code": 404,
"message": "Campaign 5a9d595701c85b37224ab2d0 could not be found.",
}
Send survey (Deprecated) ¶
Send survey
POST/api/v2/nps/customers/survey
Parameters
-
campaign: (required, string) - The campaign identifier from ‘Get campaigns’ request;
-
subscribers: (required, array) - An array of subscriber emails;
- email: john.smith@example.com (required, string) - Email address;
- first_name: john (optional, string) - First name;
- last_name: smith (optional, string) - Last name;
- company: ACME (optional, string) - Company name;
- tags (optional, array) - An array of tags. Example: [“foo”, “bar”, “baz”];
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"campaign": "5a9d595701c85b37224ab2d0",
"subscribers": [
{
"email": "john.smith@example.com",
"first_name": "",
"last_name": "",
"company": "",
"tags": [
"csv"
]
}
]
}
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"johnsmith@example.com": {
"id": "5aba3a5297e42bd3534f439e",
"email": "johnsmith@example.com",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"csv"
],
"status": "sending",
"reason": ""
}
}
}
403
Headers
Content-Type: application/json
Body
{
"code": 403,
"message": "Campaign is not enabled.",
"data": {}
}
404
Headers
Content-Type: application/json
Body
{
"code": 404,
"success": false,
"message": "Campaign not found.",
"campaign": null
}
Add feedback topics ¶
Add feedback topics
POST/api/v2/response/topics
Parameters
-
id: 5a9d595701c85b37224ab2d0 (required, string) - Response ID;
-
topics (array of objects) - An array of objects, each one including a topic name and sentiment (if sentiment is not provided, then the topic will be added with a “neutral” sentiment);
-
op: override (optional, string) - Use the flag “append” in order to append the topics to the response, or leave it empty in order to override existing topics assigned to the response;
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"id":"5a9d595701c85b37224ab2d0",
"topics": [
{
"name": "Product",
"sentiment": "positive"
},
{
"name": "Customer Support",
"sentiment": "neutral"
},
{
"name": "Pricing",
"sentiment": "negative"
}
],
"op": "append"
}
200
Headers
Content-Type: application/json
Body
{
"message": "Request successfully sent.",
"code": 200
}
Unsubscribe customers ¶
Unsubscribe customers
POST/api/v2/nps/customers/unsubscribe
Parameters
-
message: (optional, array) - Opt out message;
-
subscribers: (required, array) - An array of subscriber emails;
- email: john.smith@example.com (required, string) - Email address;
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"message": "Unsubscribed by owner.",
"subscribers": [
{
"email": "john.smith@example.com"
}
]
}
200
Headers
Content-Type: application/json
Body
{
"message": "Customers was successfully unsubscribed.",
"code": 200,
"data": [
{
"email": "john.smith@example.com",
"unsubscribed": true
}
]
}
Delete customers ¶
Delete customers
DELETE/api/v2/nps/customers
Parameters
- subscribers: (required, array) - An array of subscriber emails;
- email: john.smith@example.com (required, string) - Email address;
Example URI
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"subscribers": [
{
"email": "john.smith@example.com"
}
]
}
200
Headers
Content-Type: application/json
Body
{
"message": "Customers were successfully deleted.",
"code": 200,
"data": [
{
"email": "john.smith@example.com",
"deleted": true
}
]
}