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" : "2020-01-12",
          "promoters" : 292,
          "passives" : 194,
          "detractors" : 25,
          "total" : 511,
          "score" : 52
        },
        {
          "day" : "2020-01-13",
          "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
      }
    }
  ]
}

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"
        ],
        "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"
        ],
        "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/nps/templates

Example URI

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

GET 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 is endpoint returns all active transactional campaigns from your account.
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 4 types of properties (string, date, integer, collection);
    • “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.

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"
        }
      ]
    }
  ]
}
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/nps/audience/survey

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 4 types of properties (string, date, integer, collection);
    • 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.

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/nps/audience/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"
        }
      ]
    }
  ]
}
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
}

Update feedback tags

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