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

Sending to people

Create or update a person and schedule a survey email.

You can add properties to a survey request by passing the properties[key]=value parameter. Sending this data is useful for filtering responses on the dashboard (e.g. you might send “Location”). You can also use properties to integrate the API across different software tools. For example, if you have a unique customer ID that is used across all of your other tools, you could send it as a property to continue that link within Delighted. You can add as many properties as you like for each person.

Check out our properties guide for more information on how to segment your feedback.

You can create a person without scheduling a survey email by passing the send=false parameter. This is useful if you wish to handle surveying the person yourself and add your own survey response data via our API.

Survey throttling

Depending on the survey throttling interval set on your account, it’s possible that a person you add via the API will not be sent a survey if they have been sent one recently.

Endpoint 

POST /v1/people.json

Example request

Curl Ruby Node.js Python PHP 
curl https://api.delighted.com/v1/people.json \
  -u YOUR_DELIGHTED_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
      "email": "jony@appleseed.com",
      "properties": { "Purchase Experience": "Mobile App", "State": "CA" }
    }'
Delighted::Person.create(
  email: "jony@appleseed.com",
  properties: { "Purchase Experience" => "Mobile App", "State": "CA" }
)
// returns a promise
delighted.person.create({
  email: 'jony@appleseed.com',
  properties: { "Purchase Experience": "Mobile App", "State": "CA" }
});
delighted.Person.create(email='jony@appleseed.com',
                        properties={'Purchase Experience': 'Mobile App', 'State': 'CA'})
\Delighted\Person::create([
  'email' => 'jony@appleseed.com',
  'properties' => [
      'Purchase Experience' => 'Mobile App',
      'State' => 'CA'
  ]
]);

Example response 

{
  "id": "1",
  "email": "jony@appleseed.com",
  "name": null,
  "survey_scheduled_at": 1734839327,
  "properties": { "Purchase Experience": "Mobile App", "State": "CA" }
}

Parameters

Name Type Description
email String Email of the person (required if phone_number is not provided).
phone_number String

Phone number of the person (required if channel is sms).

The phone number format must be E.164 (e.g. +17132746524). The value should start with a + followed by the country code and then the number. The value should contain only + and digits, no spaces or other punctuation.
channel String Survey channel. Specify sms and provide a phone_number to have the survey request sent via SMS. Specify email, or leave out the option, to have the survey request sent via email.
name String Name of the person.
delay Integer The amount of seconds to wait before sending the survey email. The default is 0 (i.e. it will send immediately). This parameter will be ignored if you set send=false. There is no maximum delay.
properties Map/Dictionary

Custom properties to associate with the survey. You can add as many properties as you need. For each property you wish to add, pass a separate properties[key]=value parameter.

For example, if you wanted to add a “Customer ID” and a “Location”, you would you could pass 2 parameters, properties[customer_id]=123 and properties[location]=USA

You can optionally set a custom Question Product Name to be used in the survey question. For example, our fictitious clothing company, Hem & Stitch, could pass properties[question_product_name]=The Classic Oxford which would result in the following question being shown in the survey: “How likely are you to recommend The Classic Oxford to a friend?”. Check out our help page for more information on this special property.

You can optionally set a custom Delighted Email Subject to be used in the survey email (150 character limit). For example, our fictitious clothing company, Hem & Stitch, could pass properties[delighted_email_subject]=Tell us what you think which would result in the following subject being used in the survey email: “Tell us what you think”. Check out our help page for more information on this special property.

You can optionally set a custom Delighted Intro Message to be used in the survey email (300 character limit). For example, our fictitious clothing company, Hem & Stitch, could pass properties[delighted_intro_message]=How was your recent purchase? which would be displayed in the survey email. Check out our help page for more information on this special property.

You can optionally set a specific Locale to be used in the survey experience. This will determine localization (including language) of the survey experience. This locale string is composed of a lowercase ISO 639-1 language code and an optional uppercase ISO 3166-1 alpha-2 country code, separated by a hyphen. For example, to specify German, pass locale=de, or to specify Chinese (Simplified), pass locale=zh-CN.

We currently support the following locales: ar/Arabic, bg/Bulgarian, zh-CN/Chinese (Simplified), zh-HK/Chinese (Traditional, Hong Kong), zh-TW/Chinese (Traditional, Taiwan), hr/Croatian, cs/Czech, da/Danish, nl/Dutch, en/English, et/Estonian, fi/Finnish, fr/French, ka/Georgian, de/German, el/Greek, he/Hebrew, hu/Hungarian, id/Indonesian, it/Italian, ja/Japanese, ko/Korean, lv/Latvian, lt/Lithuanian, ms/Malaysian, nb/Norwegian Bokmål, pl/Polish, pt-BR/Portuguese (Brazil), pt/Portuguese (Portugal), ro/Romanian, ru/Russian, sr/Serbian, es/Spanish, sv/Swedish, th/Thai, tr/Turkish, and vi/Vietnamese. If you pass a value which is not in this list, the default en/English locale will be used. Please get in touch with us if you would like us to add a locale.

You can optionally configure the thank you page with a custom message and link. For example, pass properties[thank_you_message]=message which will display in the thank you page, once the survey has been completed. You can also pass properties[thank_you_link_text]=text, and properties[thank_you_link_url]=url to configure the link displayed on the thank you page. Check out our help page for more information on these special properties.

send Boolean Set to false if you do not want to send a survey email. The default is true.
last_sent_at Timestamp An optional Unix timestamp to manually set the time a person was most recently sent a survey. This value will be considered by the survey throttling system. Formatting example (for the current time): 1734835727.
email_update String

Optional field to update the person's email. If you wish to update a person's email, you need to send the old email via the email parameter, and the new email via the email_update parameter.

For example, to update clientA@delighted.com to clientB@delighted.com, you would pass the following: email=clientA@delighted.com and email_update=clientB@delighted.com.

You may want to update a person's email, but not survey them. In this case, also pass the send=false parameter. This will update the person's email, but not attempt to survey them.

phone_number_update String

Optional field to update the person's phone number. If you wish to update a person's phone number, you need to send the old number via the phone_number parameter, and the new number via the phone_number_update parameter.

For example, to update +18880000000 to +18881111111, you would pass the following: phone_number=+18880000000 and phone_number_update=+18881111111.

You may want to update a person's phone number, but not survey them. In this case, also pass the send=false parameter. This will update the person's phone number, but not attempt to survey them.