Back to top

Retently API

API

Retently NPS API (v2) endpoints

Get customers

Get 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
email
string (optional) Example: email=john@example.com

Find a customer by the email address;

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}}
Response  200
HideShow
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

GET https://app.retently.com/api/v2/nps/customers/5a9d595701c85b38114b5a1
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": {
    "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
  }
}
Response  400
HideShow
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"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Account not found.",
  "code": 401,
  "error": null
}
Response  404
HideShow
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

GET https://app.retently.com/api/v2/companies?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'

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
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{your_api_key}}
Response  200
HideShow
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
      },
    ],
  }
                                    }
Response  400
HideShow
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]]"
                                    }
Response  401
HideShow
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

GET   https://app.retently.com/api/v2/companies/60444db01eeeb6bf89799999
GET   https://app.retently.com/api/v2/companies/acme.com
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{your_api_key}}
Response  200
HideShow
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
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Account not found",
  "code": 401,
  "data": null
                                    }
{
  "message": "Missing authorization key (api_key).",
  "code": 401,
  "data": null
                                    }
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Company record not found",
  "code": 404
                                    }

Get reports

Get reports
GET/api/v2/reports/

Example URI

GET https://app.retently.com/api/v2/reports/5f1ec45y27b8313876299999
URI Parameters
HideShow
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.

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

GET https://app.retently.com/api/v2/nps/score
GET https://app.retently.com/api/v2/star/score
GET https://app.retently.com/api/v2/csat/score
GET https://app.retently.com/api/v2/ces/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": "Account not found",
  "code": 401,
  "data": null
}

Get feedback

Get feedback
GET/api/v2/feedback{?page,limit,sort,startDate,endDate}

Example URI

GET https://app.retently.com/api/v2/feedback?page=1&limit=20&sort=-createdDate&startDate=1514764800&endDate=1526556971
URI Parameters
HideShow
email
string (optional) Example: john@example.com

Search responses by a customer’s email address;

customerId
string (optional) Example: customerId=5f1faaa4b4e2e4963e41893b

Search responses by a customer’s Retently ID;

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 ‘-createdDate’ for results in descending order.
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": [
      {
        "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

GET https://app.retently.com/api/v2/feedback/5a9d595701c85b37224ab2d0
feedbackId
string Example: '5a9d595701c85b37224ab2d0'
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": [
      {
        "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
  }
}
Response  400
HideShow
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
                                    }
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Account not found",
  "code": 401,
  "data": null
                                    }
Response  404
HideShow
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

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": "",
        "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

GET  https://app.retently.com/api/v2/nps/outbox?page=1&limit=50
URI Parameters
HideShow
email
string (optional) Example: email=john@example.com

Find a customer’s outbox records by email address;

page
string (optional) Example: 1

The current page number. Default 1;

limit
string (optional) Example: 50

The items limit. Default 50;

sort
string (optional) Example: 'surveyCreatedDate'

The sort option. Use ‘-surveyCreatedDate’ for results in descending order; Default ‘-surveyCreatedDate’;

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": {
    "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

GET https://app.retently.com/api/v2/templates
Included in response:
  • list with templates (except deleted templates)
  • template id
  • template name
  • template channel
  • template metric
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response  200
HideShow
Headers
Content-Type: application/json
Body

{
"code": 200,
"message": "Success.",
"templates": [
    {
        "id": "628765bf8743956",
        "name": "Default NPS in-app template", 
        "channel": "inapp", 
        "metric": "STAR" 
    }
]
}
Response  401
HideShow
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

GET https://app.retently.com/api/v2/nps/templates

Note:

This endpoint is deprecated.
Please use the new endpoint: https://app.retently.com/api/v2/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/campaigns

Example URI

GET https://app.retently.com/api/v2/campaigns

Note:

This endpoint returns all campaigns from your account (except deleted campaigns).
  • list with campaigns (except deleted campaigns)
  • campaign id
  • campaign status
  • campaign name
  • assigned template id
  • campaign metric
  • campaign channel
  • campaign type
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Response  200
HideShow
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"
    }
]
}
Response  401
HideShow
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

GET https://app.retently.com/api/v2/nps/campaigns

Note:

This endpoint is deprecated.
Please use the new endpoint: https://app.retently.com/api/v2/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

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.
Learn more about managing properties via API

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"
      ],
      "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
        }
      ]
    }
  ]
}
Response  200
HideShow
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/survey

The /api/v2/nps/audience/survey is planned to be deprecated, and if you’re already using it in your requests, please consider updating it to /api/v2/survey.

For transactional in-app survey

If you’re considering using this endpoint to schedule transactional in-app surveys, ensure you’ve installed the in-app script in your web application first. Read tutorial.

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.

Learn more about managing properties via API

Note:

If your request includes customers that were previously added to Retently, then their data will be updated with the information you will pass in the current request.

Example URI

POST https://app.retently.com/api/v2/survey
Request
HideShow
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
        }
      ]
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true,
  "code": 200,
  "message": "Success.",
  "status": "queued"
}
Response  400
HideShow
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",
    }
  ]
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "message": Invalid API key.,
  "code": 401,
  "data": null,
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "success": false,
  "status": "error",
  "code": 403,
  "message": "Campaign 5a9d595701c85b37224ab2d0 is not active.",
                                    }
Response  404
HideShow
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

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
}

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

POST https://app.retently.com/api/v2/response/topics
Request
HideShow
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"
                                    }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Request successfully sent.",
  "code": 200
}

Add feedback tags

Add feedback tags
POST/api/v2/response/tags

Parameters

  • id: 5a9d595701c85b37224ab2d0 (required, string) - Response ID;

  • tags (array) - An array of tags;

  • op: override (optional, string) - Use the flag “append” in order to append the tags to the response, or leave it empty in order to override existing tags;

Example URI

POST https://app.retently.com/api/v2/response/tags
Request
HideShow
Headers
Content-Type: application/json
Authorization: api_key={{api_key}}
Body
{
    "id":"5a9d595701c85b37224ab2d0",
    "tags": [ "Product 1", "Order status" ],
    "op": "append"
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Request successfully sent.",
  "code": 200
}

Update feedback tags (Deprecated)

Update feedback 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"
}
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;

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;

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 were successfully deleted.",
  "code": 200,
  "data": [
    {
      "email": "john.smith@example.com",
      "deleted": true
    }
  ]
}

Generated by aglio on 09 Oct 2018