1. Sign in

API documentation

Table of contents

  1. Introduction
  2. Libraries
  3. Sending to people
  4. Listing survey responses
  5. Getting metrics
  6. Adding survey responses
  7. Deleting pending survey requests
  8. Unsubscribing people
  9. Listing people
  10. Listing unsubscribed people
  11. Listing bounced people
  12. Deleting people
  13. Getting Autopilot configuration
  14. Listing people in Autopilot
  15. Adding people to Autopilot
  16. Removing people from Autopilot
  17. Webhooks
  18. Web snippet

Introduction

This guide will walk you through the process of setting up Delighted using the REST API.

Note: All parameters and values are case-sensitive.

Authentication

To use the Delighted API, you’ll need a private API key that is linked to your account. Each CX project has its own API key, so ensure you’ve selected the correct project in the top left-hand corner. Please contact your account admin to obtain your Delighted API key.

Be sure to keep your API key private. All API requests must be made over HTTPS and are authenticated via HTTP Basic Auth. Use your API key as the username and leave the password blank.

HTTP status codes

All endpoints use conventional HTTP status codes. The specific codes returned are listed below with a brief explanation.

Code Description
200 Indicates that the request was successful.
201 Indicates that the request was successful and a new resource was created.
202 Indicates that the request was accepted but has not been completely processed yet.
401 Indicates the API key was invalid.
403 Indicates the API feature is not available on your current plan.
406 Indicates that the format of the request was not correct. Endpoints only support JSON. You can either pass the Accept: application/json header or suffix the request URL with .json.
422 Indicates the request was invalid. This usually means some of the required parameters were missing. Information about the specific errors will be returned in the response.
429 Indicates the request was rate limited. You may need to reduce the frequency of your requests. The Retry-After response header contains the number of seconds you should wait before retrying. See the “Rate Limits” section below for more details.
500 Indicates that we are having trouble on our end.
503 Indicates that we are currently down for maintenance.

Below is an example 422 response. This illustrates how errors are provided for specific attributes of the resource (in this case, a Person): 

{
  "status": 422,
  "message": "Unprocessable Entity",
  "errors": {
    "email": ["can't be blank", "is invalid"],
    "name": ["must be less than 255 characters"]
  }
}

Rate Limits

In order to provide a high quality of service to all users of our API we may rate limit requests in certain extreme usage scenarios. It is very unlikely for you to experience rate limits with normal usage of our API. The most common reasons for you to experience rate limiting are bugs or bulk data requests.

If you start receiving 429 HTTP responses, please reduce the frequency of your requests. Each failed request can safely be retried. We recommend using an exponential backoff strategy, by first waiting one second after receiving a 429 before trying again. If your request continues to receive a 429, wait two seconds, then four seconds, etc. Alternatively, you can look at the value of the Retry-After header on the response to know exactly how many seconds you should wait before retrying. Our official libraries include support for handling rate limit errors (details: Ruby, PHP, Node.js, Python).

If you are experiencing persistent trouble with rate limits, please get in touch.