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

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

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
}

Update response tags ¶

Update response tags
POST`/api/v2/nps/customers/response/tags`

Parameters

id: 5a9d595701c85b37224ab2d0 (required, string) - Response ID;
tags (optional, array) - An array of tags. Example: [“foo”, “bar”, “baz”];
op: override (optional, string) - Use the flag “append” in order to append the tags to the response, or leave empty in order to override existing tags;

Example URI

POST https://app.retently.com/api/v2/nps/customers/response/tags

Request

HideShow

Headers

Content-Type: application/json
Authorization: api_key={{api_key}}

Body

{
    "id":"5a9d595701c85b37224ab2d0",
    "tags": [ "foo", "bar" ]
    "op": "append" // override
}

Response 200

HideShow

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

POST https://app.retently.com/api/v2/nps/customers/unsubscribe

Request

HideShow

Headers

Content-Type: application/json
Authorization: api_key={{api_key}}

Body

{
  "message": "Unsubscribed by owner.",
  "subscribers": [
    {
      "email": "john.smith@example.com"
    }
  ]
}

Response 200

HideShow

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

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
    }
  ]
}

API ¶

List customers ¶

List customersGET/api/v2/nps/customers{?page,limit,sort}

Example URI

Headers

Body

Headers

Body

Get latest score ¶

Get latest scoreGET/api/v2/nps/score

Example URI

Headers

Body

Headers

Body

Headers

Body

Get latest response ¶

Get latest responseGET/api/v2/nps/customers/response{?page,limit,sort,startDate,endDate}

Example URI

Headers

Headers

Body

Get templates ¶

Get templatesGET/api/v2/nps/templates

Example URI

Headers

Headers

Body

Get campaigns ¶

Get campaignsGET/api/v2/nps/campaigns

Example URI

Headers

Headers

Body

Headers

Body

Create or update customers ¶

Create or update customersPOST/api/v2/nps/customers

Example URI

Headers

Body

Headers

Body

Send survey ¶

Send surveyPOST/api/v2/nps/customers/survey

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Update response tags ¶

Update response tagsPOST/api/v2/nps/customers/response/tags

Example URI

Headers

Body

Headers

Body

Unsubscribe customers ¶

Unsubscribe customersPOST/api/v2/nps/customers/unsubscribe

Example URI

Headers

Body

Headers

Body

Delete customers ¶

Delete customersDELETE/api/v2/nps/customers

Example URI

Headers

Body

Headers

Body

List customers
GET`/api/v2/nps/customers{?page,limit,sort}`

Get latest score
GET`/api/v2/nps/score`

Get latest response
GET`/api/v2/nps/customers/response{?page,limit,sort,startDate,endDate}`

Get templates
GET`/api/v2/nps/templates`

Get campaigns
GET`/api/v2/nps/campaigns`

Create or update customers
POST`/api/v2/nps/customers`

Send survey
POST`/api/v2/nps/customers/survey`

Update response tags
POST`/api/v2/nps/customers/response/tags`

Unsubscribe customers
POST`/api/v2/nps/customers/unsubscribe`

Delete customers
DELETE`/api/v2/nps/customers`