Retently API

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"
        ],
        "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/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/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 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/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"
        },
        {
            "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
}

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;
- email: john.smith@example.com (required, string) - Email address;

Example URI

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

Request

HideShow

Headers

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

Body

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

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "Customers was successfully unsubscribed.",
  "code": 200,
  "data": [
    {
      "email": "john.smith@example.com",
      "unsubscribed": true
    }
  ]
}

Delete customers ¶

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

Parameters

subscribers: (required, array) - An array of subscriber emails;
- email: john.smith@example.com (required, string) - Email address;

Example URI

DELETE https://app.retently.com/api/v2/nps/customers

Request

HideShow

Headers

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

Body

{
  "subscribers": [
    {
      "email": "john.smith@example.com"
    }
  ]
}

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
  "message": "Customers were successfully deleted.",
  "code": 200,
  "data": [
    {
      "email": "john.smith@example.com",
      "deleted": true
    }
  ]
}

API ¶

Get customers ¶

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

Example URI

Headers

Headers

Body

Get customer by ID ¶

Get customer by ID GET/api/v2/nps/customers/{customerId}

Example URI

Headers

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Get companies ¶

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

Example URI

Headers

Headers

Body

Headers

Body

Headers

Body

Get company by id ¶

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

Example URI

Headers

Headers

Body

Headers

Body

Headers

Body

Get reports ¶

Get reports GET/api/v2/reports/

Example URI

Headers

Headers

Body

Get latest score ¶

Get latest score GET /api/v2/{metric}/score

Example URI

Headers

Body

Headers

Body

Headers

Body

Get feedback ¶

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

Example URI

Headers

Headers

Body

Get feedback by id ¶

Get feedback by id GET/api/v2/feedback/{feedbackId|campaignId}

Example URI

Headers

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Get responses (Deprecated) ¶

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

Example URI

Headers

Headers

Body

Get outbox ¶

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

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

Get customer by ID
GET`/api/v2/nps/customers/{customerId}`

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

Get company
GET`/api/v2/companies/{companyId|domain}`

Get reports
GET`/api/v2/reports/`

Get latest score
GET`/api/v2/{metric}/score`

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

Get feedback by id
GET`/api/v2/feedback/{feedbackId|campaignId}`

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

GET OUTBOX
GET`/api/v2/nps/outbox{?page, limit}`

Get templates
GET`/api/v2/templates`

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

Get campaigns
GET`/api/v2/campaigns`

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

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

Send transactional survey
POST`/api/v2/nps/audience/survey`

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