Retently NPS API (v2)

REST API Reference Documentation

API DETAILS

Base URL:https://app.retently.com
API Version:v2
Rate Limits:150 requests/min

AUTHENTICATION

Header Authentication

Recommended

This is the default and most secure method. Send your API key in the request header.

GET /api/v2/feedback
Content-Type: application/json
Authorization: api_key=YOUR_KEY
✓Any tool or client that supports custom headers should use this method.

Query Parameter Authentication

Not Recommended

This method sends the API key as a query parameter. Use it only when header-based authentication is not possible. For example, some tools like Microsoft Power Automate may strip or sanitize custom headers before the request reaches our API.

GET /api/v2/feedback?api_key=YOUR_KEY
⚠️Security Warning
  • API keys in URLs can be logged by browsers, proxies, and servers.
  • URLs may be cached or stored in browser history.
  • Only use this method if your tool does not support custom headers.
See both authentication options in action

GET CUSTOMERS

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

Retrieves a paginated list of customers, allowing you to filter, sort, and search by email, or sort the data by creation date.

EXAMPLE URI

https://app.retently.com/api/v2/customers?page=1&limit=20&sort=createdDate
URI Parameters
email
string(optional)
Example: [email protected]

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. Maximum 1,000;

sort
string(optional)
Example: 'createdDate'

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

startDate
string(optional)
Example: '2022-01-01T00:00:00Z' or '1514764800'

ISO format or UNIX timestamp;

endDate
string(optional)
Example: '2018-05-17T17:36:11Z' or '1526556971'

ISO format or UNIX timestamp;

Request
Response200

GET CUSTOMER BY ID

GET/api/v2/customers/{customerId}

Retrieves detailed information about a specific customer by their unique customer ID.

EXAMPLE URI

https://app.retently.com/api/v2/customers/5a9d595701c85b38114b5a1
Request
Response200
Response400
Response401
Response404

GET COMPANIES

GET/api/v2/companies{?page,limit,sort}

Retrieves a paginated list of companies, including details like industry, tags, NPS, CSAT or CES metrics, and customer counts per company.

EXAMPLE URI

https://app.retently.com/api/v2/companies?page=1&limit=20&sort=-createdDate
URI Parameters
page
integer(optional)
Example: 1

The current page number. Default 1;

limit
integer(optional)
Example: 20

The items limit. Default 20. Maximum 1,000;

sort
string(optional)
Example: 'createdDate'

Use “-” to pull results in descending order. Example: sort=-companyName

Request
Sort Options
Response200
Response400
Response401

GET COMPANY BY ID

GET/api/v2/companies/{companyId|domain}

Retrieves detailed information about a specific company using its unique ID or domain name.

EXAMPLE URIS

https://app.retently.com/api/v2/companies/60444db01eeeb6bf89799999
https://app.retently.com/api/v2/companies/acme.com
Request
Response200
Response401
Response404

GET REPORTS

GET/api/v2/reports/

Retrieves reports for one or all survey campaigns, including trend data, delivery stats, and additional rating questions stats.

EXAMPLE URI

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

Date range
string(optional)

Data is returned in account's timezone.

Request
Response200

GET LATEST SCORE

GET/api/v2/{metric}/score

Retrieves the most recent score for a specific survey metric (NPS, CSAT, CES, or STAR) along with rating distribution and response counts.

EXAMPLE URIS

https://app.retently.com/api/v2/nps/score
https://app.retently.com/api/v2/star/score
https://app.retently.com/api/v2/csat/score
https://app.retently.com/api/v2/ces/score
Request
Response200
Response401

GET FEEDBACK

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

Retrieves customer survey responses, allowing you to filter by customer (email or ID), campaign, date range, or other attributes and view detailed response data.

EXAMPLE URI

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

Search responses by a customer’s email address;

customerId
string(optional)
Example: customerId=5f1faaa4b4e2e4963e41893b

Search responses by a customer’s Retently ID;

campaignId
string(optional)
Example: campaignId=663a4c44ce3cceb3d50c2793

Filter responses by a specific campaign ID;

page
string(optional)
Example: 1

The current page number. Default 1;

limit
string(optional)
Example: 20

The items limit. Default 20. Maximum 1,000;

sort
string(optional)
Example: 'createdDate'
startDate
string(optional)
Example: '1514764800'

UNIX timestamp;

endDate
string(optional)
Example: '1526556971'

UNIX timestamp;

Request
Response200

GET FEEDBACK BY ID

GET/api/v2/feedback/{feedbackId}

Retrieves detailed information about a specific survey response using its unique feedback ID.

EXAMPLE URI

https://app.retently.com/api/v2/feedback/5a9d595701c85b37224ab2d0
Request
Response200
Response400
Response401
Response404

GET OUTBOX

GET/api/v2/outbox{?page, limit}

Retrieves a paginated list of sent surveys with delivery status and recipient details.

EXAMPLE URI

https://app.retently.com/api/v2/outbox?page=1&limit=20
URI Parameters
email
string(optional)
Example: [email protected]

Find a customer’s outbox records by email address;

page
string(optional)
Example: 1

The current page number. Default 1;

limit
string(optional)
Example: 20

The items limit. Default 20. Maximum 1,000;

sort
string(optional)
Example: 'surveyCreatedDate'

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

Request
Response200

GET TEMPLATES

GET/api/v2/templates

Retrieves a list of survey templates with their names, channels, and associated metrics.

EXAMPLE URI

https://app.retently.com/api/v2/templates
Request
Response200
Response401

GET CAMPAIGNS

GET/api/v2/campaigns

Retrieves a list of survey campaigns with details such as name, metric type, channel, associated survey template, and status (active or deactivated).

EXAMPLE URI

https://app.retently.com/api/v2/campaigns
Request
Notes
Response200
Response401

CREATE OR UPDATE CUSTOMERS

POST/api/v2/customers

Creates or updates customers in bulk (up to 1,000 per request), including customer attributes.

EXAMPLE URI

https://app.retently.com/api/v2/customers
Request Body Parameters
  • subscribers:arrayrequired- An array of customers
    • email:[email protected]stringrequired- Email address
    • first_name:Johnstringoptional- First name
    • last_name:Smithstringoptional- Last name
    • company:ACMEstringoptional- Company name
    • tags:arrayoptional- An array of tags. Example: [“foo”, “bar”, “baz”]
Request
Manage customer properties
Response200

SEND TRANSACTIONAL SURVEY

POST/api/v2/survey

Queues for sending a transactional email or in-app survey via the specified campaign to one or more customers, with the possibility to condifure a survey delay.

EXAMPLE URI

https://app.retently.com/api/v2/survey
Request Body Parameters
  • campaign:stringrequired- The campaign ID where your customers will be surveyed
  • delay:integeroptional- Send the survey at a later day from the triggered event. The delay is counted in days (e.g., “delay“: 7);
  • subscribers:arrayrequired- An array of objects that may contain 1 or up to 100 customers per request. Each customer object may include the following parameters:
    • email:stringrequired- A variable with the email address of the customer
    • first_name:stringoptional- A variable with the first name of the customer
    • last_name:stringoptional- A variable with the last name of the customer
    • company:stringoptional- A variable with the company name of the customer
    • tags:arrayoptional- Any data passed in the array, will be imported as tags along with the customer. Example: [“foo”, “bar”, “baz”]
Request
Manage customer properties
For transactional in-app survey
Note
Response200
Response400
Response401
Response403
Response404

ADD FEEDBACK TOPICS

POST/api/v2/response/topics

Adds or updates feedback topics for a specific survey response, allowing you to classify it by theme and sentiment.

EXAMPLE URI

https://app.retently.com/api/v2/response/topics
Request Body Parameters
  • id:5a9d595701c85b37224ab2d0stringrequired- Response ID;
  • topics:array of objectsoptional- An array of topic objects
    • name:Usabilitystringrequired- The topic name
    • sentiment:positivestringoptional- The sentiment of the topic (if not provided, defaults to 'neutral')
  • op:overridestringoptional- 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;
Request
Response200

ADD FEEDBACK TAGS

POST/api/v2/response/tags

Adds or updates feedback tags for a specific survey response, with the option to append new tags or replace existing ones.

EXAMPLE URI

https://app.retently.com/api/v2/response/tags
Request Body Parameters
  • id:5a9d595701c85b37224ab2d0stringrequired- Response ID;
  • tags:arrayoptional- An array of tags;
  • op:overridestringoptional- Use the flag “append” in order to append the tags to the response, or leave it empty in order to override existing tags;
Request
Response200

UNSUBSCRIBE CUSTOMERS

POST/api/v2/customers/unsubscribe

Unsubscribes one or more customers from receiving future surveys, optionally including a custom opt-out message.

EXAMPLE URI

https://app.retently.com/api/v2/customers/unsubscribe
Request Body Parameters
  • message:arrayoptional- Opt out message
  • subscribers:arrayrequired- An array of subscriber emails
Request
Response200

DELETE CUSTOMERS

DELETE/api/v2/customers

Deletes one or more customers and all their associated data using their email addresses for identification.

EXAMPLE URI

https://app.retently.com/api/v2/customers
Request Body Parameters
  • subscribers:arrayrequired- An array of subscriber emails
Request
Response200

GET RESPONSES (DEPRECATED)

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

EXAMPLE URI

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

The current page number. Default 1;

limit
string(optional)
Example: 20

The items limit. Default 20. Maximum 1,000;

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
Response200

GET TEMPLATES (DEPRECATED)

GET/api/v2/nps/templates

EXAMPLE URI

https://app.retently.com/api/v2/nps/templates
Request
Notes
Response200

GET CAMPAIGNS (DEPRECATED)

GET/api/v2/nps/campaigns

EXAMPLE URI

https://app.retently.com/api/v2/nps/campaigns
Request
Notes
Response200
Response404

SEND SURVEY (REMOVED)

POST/api/v2/nps/customers/survey
The /api/v2/nps/customers/survey endpoint has been removed, and all requests to this endpoint will now return an error. If you are currently using this endpoint or planning to use our API to trigger surveys, please switch to the /api/v2/survey endpoint here.

EXAMPLE URI

https://app.retently.com/api/v2/nps/customers/survey
Request Body Parameters
  • campaign:stringrequired- The campaign identifier from ‘Get campaigns’ request
  • subscribers:arrayrequired- An array of subscriber emails
    • email:[email protected]stringrequired- Email address
    • first_name:johnstringoptional- First name
    • last_name:smithstringoptional- Last name
    • company:ACMEstringoptional- Company name
    • tags:arrayoptional- An array of tags. Example: [“foo”, “bar”, “baz”]
Request
Response200
Response403
Response404

UPDATE FEEDBACK TAGS (DEPRECATED)

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

EXAMPLE URI

https://app.retently.com/api/v2/nps/customers/response/tags
Request Body Parameters
  • id:5a9d595701c85b37224ab2d0stringrequired- Response ID;
  • tags:arrayoptional- An array of tags. Example: [“foo”, “bar”, “baz”];
  • op:overridestringoptional- Use the flag “append” in order to append the tags to the response, or leave empty in order to override existing tags;
Request
Response200