API documentation

Sending to people

Create or update a person and schedule a survey email.

You can add properties to a person 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.


POST /v1/people.json

Example request

curl https://api.delighted.com/v1/people.json \
  -H "Content-Type: application/json" \
  -d '{
      "email": "jony@appleseed.com",
      "properties": { "Purchase Experience": "Mobile App" }
  email: "jony@appleseed.com",
  properties: { "Purchase Experience" => "Mobile App" }
// returns a promise
  email: 'jony@appleseed.com',
  properties: { "Purchase Experience": "Mobile App" }
                        properties={'Purchase Experience': 'Mobile App'})
  'email' => 'jony@appleseed.com',
  'properties' => [
      'Purchase Experience' => 'Mobile App'

Example response

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


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?”.

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”.

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.

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): 1580064764.