Back to top

Retently API

API

Retently NPS API (v2) endpoints

List customers

List customers
GET/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
HideShow
page
integer (optional) Example: 1

The current page number. Default 1;

limit
integer (optional) Example: 20

The items limit. Default 20;

sort
string (optional) Example: 'createdDate'

The sort option. Use ‘-’ for DESC. Default ‘-createdDate’;

Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{}
Response  200
HideShow
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 score
GET/api/v2/nps/score

Example URI

GET https://app.retently.com/api/v2/nps/score
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{}
Response  200
HideShow
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
HideShow
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 response
GET/api/v2/nps/customers/response{?page,limit,sort,startDate,endDate}

Example URI

GET https://app.retently.com/api/v2/nps/customers/response?page=1&limit=20&sort='createdDate'&startDate='1514764800'&endDate='1526556971'
URI Parameters
HideShow
page
string (optional) Example: 1

The current page number. Default 1;

limit
string (optional) Example: 20

The 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;

Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response  200
HideShow
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,
    "startDate": "1514764800",
    "endDate": "1526556971"
  }
}

Get templates

Get templates
GET/api/v2/nps/templates

Example URI

GET https://app.retently.com/api/v2/nps/templates
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5a9cff9e48c0809113087557",
    "value": "DRUPAL template"
  },
  {
    "id": "5a9cf2ba48c0809113087506",
    "value": "HEXAGON template"
  }
]

Get campaigns

Get campaigns
GET/api/v2/nps/campaigns

Example URI

GET https://app.retently.com/api/v2/nps/campaigns
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "id": "5a9d595701c85b37224ab2d0",
    "value": "Transactional NPS campaign"
  }
]
Response  404
HideShow
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

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
HideShow
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
HideShow
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 survey
POST/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
HideShow
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
HideShow
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
HideShow
Headers
Content-Type: application/json
Body
{
  "code": 403,
  "message": "Campaign is not enabled.",
  "data": {}
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "code": 404,
  "success": false,
  "message": "Campaign not found.",
  "campaign": null
}

Delete customers

Delete customers
DELETE/api/v2/nps/customers

Parameters

  • subscribers: (required, array) - An array of subscriber emails;

Example URI

DELETE https://app.retently.com/api/v2/nps/customers
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
  "subscribers": [
    {
      "email": "john.smith@example.com"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Customers was successfully deleted.",
  "code": 200,
  "data": [
    {
      "email": "john.smith@example.com",
      "deleted": true
    }
  ]
}

Generated by aglio on 17 May 2018