Retently API
API ¶
Retently NPS API (v2) endpoints
List customers ¶
List customersGET/api/v2/nps/customers{?page,limit,sort}
Example URI
GET https://app.retently.com/api/v2/nps/customers?page=1&limit=20&sort='createdDate'
URI Parameters
- 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’;
Request
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{}
Response
200
Headers
Content-Type: application/json
Body
{
"message": "Success.",
"code": 200,
"data": {
"subscribers": [
{
"email": "tombrown@example.com",
"firstName": "Tom",
"lastName": "Brown",
"companyName": "ACME",
"tags": [],
"createdDate": "2018-03-23T09:28:17.640Z"
},
{
"email": "johnsmith@example.com",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"tags": [
"csv"
],
"createdDate": "2018-03-05T08:21:23.129Z"
}
],
"page": 1,
"pages": 2,
"limit": 10,
"sort": "-createdDate",
"total": 13
}
}
Get latest score ¶
Get latest scoreGET/api/v2/nps/score
Example URI
GET https://app.retently.com/api/v2/nps/score
Request
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{}
Response
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
}
}
Response
401
Headers
Content-Type: application/json
Body
{
"message": "Please check your API Key to make sure it's valid.",
"code": 401,
"data": null
}
Get latest response ¶
Get latest responseGET/api/v2/nps/customers/response{?page,limit,sort}
Example URI
GET https://app.retently.com/api/v2/nps/customers/response?page=1&limit=20&sort='createdDate'
URI Parameters
- 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’;
Request
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response
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": ""
},
{
"email": "johnsmith@example.com",
"firstName": "John",
"lastName": "Smith",
"companyName": "ACME",
"tags": [
"csv"
],
"createdDate": "2018-03-27T09:37:43.072Z",
"score": 10,
"comment": ""
}
],
"page": 1,
"pages": 1,
"limit": 2,
"total": 2
}
}
Get templates ¶
Get templatesGET/api/v2/nps/templates
Example URI
GET https://app.retently.com/api/v2/nps/templates
Request
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response
200
Headers
Content-Type: application/json
Body
[
{
"id": "5a9cff9e48c0809113087557",
"value": "DRUPAL template"
},
{
"id": "5a9cf2ba48c0809113087506",
"value": "HEXAGON template"
}
]
Get campaigns ¶
Get campaignsGET/api/v2/nps/campaigns
Example URI
GET https://app.retently.com/api/v2/nps/campaigns
Request
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response
200
Headers
Content-Type: application/json
Body
[
{
"id": "5a9d595701c85b37224ab2d0",
"value": "Transactional NPS campaign"
}
]
Response
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 customersPOST/api/v2/nps/customers
Max number of subscribers by default is 100 per request.
Parameters
- subscribers: (required, array) - An array of subscribers;
- 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”];
Example URI
POST https://app.retently.com/api/v2/nps/customers
Request
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",
"baz"
]
}
]
}
Response
200
Headers
Content-Type: application/json
Body
{
"message": "Request successfully sent.",
"code": 200,
"data": {
"john.smith@example.com": {
"email": "johnsmith@example.com ",
"first_name": "John",
"last_name": "Smith",
"company": "ACME",
"tags": [
"csv"
],
"status": "created", // failed
"reason": "" // exists|invalid email
}
}
}
Send survey ¶
Send surveyPOST/api/v2/nps/customers/survey
Parameters
- 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
POST https://app.retently.com/api/v2/nps/customers/survey
Request
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"
]
}
]
}
Response
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": ""
}
}
}
Response
403
Headers
Content-Type: application/json
Body
{
"code": 403,
"message": "Campaign is not enabled.",
"data": {}
}
Response
404
Headers
Content-Type: application/json
Body
{
"code": 404,
"success": false,
"message": "Campaign not found.",
"campaign": null
}
Delete customers ¶
Delete customersDELETE/api/v2/nps/customers
Parameters
- subscribers: (required, array) - An array of subscriber emails;
- email: john.smith@example.com (required, string) - Email address;
Example URI
DELETE https://app.retently.com/api/v2/nps/customers
Request
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
"subscribers": [
{
"email": "john.smith@example.com"
}
]
}
Response
200
Headers
Content-Type: application/json
Body
{
"message": "Customers was successfully deleted.",
"code": 200,
"data": [
{
"email": "john.smith@example.com",
"deleted": true
}
]
}