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

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
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": "[email protected]",
        "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": "[email protected]",
        "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.

Date range
string (optional): Accepted format YYYY-MM-DD
Example: ‘startDate=2024-01-01&endDate=2024-01-31’

Data is returned in account's timezone.

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,
          "ratingDistribution": {
            "1" : 4,
            "5" : 2,
            "8" : 7,
            "10" : 15
          },
          "score" : 52
        },
        {
          "day" : "2022-12-02",
          "promoters" : 292,
          "passives" : 194,
          "detractors" : 26,
          "total" : 512,
          "ratingDistribution": {
            "1" : 4,
            "5" : 2,
            "8" : 7,
            "10" : 15
          },
          "score" : 52
        }
      ],
      "last": {
        "promoters" : 292,
        "passives" : 194,
        "detractors" : 24,
        "total" : 512,
        "score" : 52,
        "ratingDistribution": {
            "1" : 4,
            "5" : 2,
            "8" : 7,
            "10" : 15
          }
      },
      "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
                }
            }
         }
      ],
      "name" : "Recurring NPS email campaign",
      "isActive" : true,
      "metric" : "NPS",
      "type" : "regular",
      "score" : "email"
    }
  ]
}

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,
    "ratingDistribution": {
        "0" : 7,
        "1" : 5,
        "2" : 3,
        "3" : 5,
        "4" : 2,
        "5" : 6,
        "6" : 1,
        "7" : 6,
        "8" : 5,
        "9" : 19,
        "10" : 42
    },
    "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: [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;

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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "firstName": "Tom",
        "lastName": "Brown",
        "companyName": "ACME",
        "tags": [],
        "createdDate": "2018-03-27T09:45:41.697Z",
        "score": 10,
        "comment": "",
        "feedbackTags": []
      },
      {
        "email": "[email protected]",
        "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 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: 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": "[email protected]",
            "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": "[email protected]",
            "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": "[email protected]",
                    "type": "cc",
                    "mandrillMessageId": "3ec992d239754081bca1f9ad1572hf93",
                },
                {
                    "email": "[email protected]",
                    "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: [email protected] (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": "[email protected]",
      "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": "[email protected]",
              "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

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;

  • delay: (optional, integer) - Send the survey at a later day from the triggered event. The delay is counted in days (e.g., “delay“: 7);

  • 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": "[email protected]",
      "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": "[email protected]",
        "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 (Removed)

Send survey
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.

Parameters

  • campaign: (required, string) - The campaign identifier from ‘Get campaigns’ request;

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

    • email: [email protected] (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": "[email protected]",
      "first_name": "",
      "last_name": "",
      "company": "",
      "tags": [
        "csv"
      ]
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Success.",
  "code": 200,
  "data": {
    "[email protected]": {
      "id": "5aba3a5297e42bd3534f439e",
      "email": "[email protected]",
      "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": "[email protected]"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Customers was successfully unsubscribed.",
  "code": 200,
  "data": [
    {
      "email": "[email protected]",
      "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": "[email protected]"
    }
  ]
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "message": "Customers were successfully deleted.",
  "code": 200,
  "data": [
    {
      "email": "[email protected]",
      "deleted": true
    }
  ]
}

Generated by aglio on 09 Oct 2018