API Documentation

In this article:

FAQs

Suggested next article: The Email Platform: Sending via Email

API overview and documentation

Application Programming Interfaces (APIs) allow applications to interact and share data. In this API integration guide, we'll share the basics of structuring your API calls, where to find important API documentation, how to test your API integrations, and a couple of common API use cases.

Delighted’s REST API allows you to push and pull information to and from Delighted to:

  • Trigger survey sends
  • Sync response data
  • Get metrics (like response rate, bounce rate, etc.)
  • Unsubscribe people
  • …and more!

All of the REST API endpoints are listed in the complete API documentation.

Documenting your API usage

It's best practice to keep record of which systems you're using to call the Delighted API—if someone else on your team ever needs to know where surveys are being triggered from or where data is flowing to, the Delighted team isn't able to help. We can't see what platform an API call came from—just that it came via the API. So keep track of this information somewhere where your team can access it!

Back to top

Structuring your API

When transitioning to the API, there are a few preliminary considerations to think through:

1
Decide on actions you’ll perform: What are your endpoints? Will you be using the API for sending, pulling out response data, or some other reason?
2
Determine the structure of your API requests: Are you sending properties or metadata to Delighted? Will you be adding a delay? What language are you using (Ruby, Python)?
3
Choose your triggers: What will trigger a survey send? Are you triggering at a milestone (like after 3 months of being a customer) or after an event (like a purchase being made)?
4
Isolate where the trigger occurs: Where will you find the event-based or milestone information triggering the survey? Does the event occur in a CRM or is it based off of an action in a proprietary system?
5
Decide on survey or event frequency: How frequently will you be calling this endpoint?
6
Gather the properties for your request: If triggering survey requests, you can pass unlimited customer information to use to segment feedback. Unsure of what information to pass? Check out section 5. Managing People and Properties.

Back to top

Key documentation for Delighted's REST API

  • API Key: Acquire the unique API key for your project under Integrations > API. Remember that limited users cannot view the API key, and each project has its own key.
  • API Documentation: Review the details necessary for API integration.
  • IP Whitelisting: If your system requires whitelisting of IP addresses to post to our API, the IP address is 107.21.230.131

Back to top

Testing and production of API integrations

Testing your API connection helps to identify potential bugs and inconsistencies before going to production.

Setting up a testing environment

Creating a testing “sandbox” Delighted account is possible in just two steps:

1
Set up a new account: Create a new trial account using an email not associated with your main Delighted account.
2
Grab your API key: Once logged into the new trial account, head to the API page to find your test project’s API key.

This is a live account, so be sure to set the sending parameter to false (more details below), or only use internal or dummy emails.

Testing best practices

  • Throttling applies: Throttling still applies, so reach out to us if you need to test multiple times with the same email.
  • Trial will expire: Need more than a few weeks to test? Let us know and we can add extra time to your sandbox trial account.
  • Set send=false: A great way to test your API integration without sending out surveys: set the send parameter to false to prevent survey emails from going out.
  • Simplicity is best: Keep initial tests simple, using only the most essential parameters (like email and name). Layer in more parameters as you continue testing.
  • Document everything: Document all outcomes, unique requests being sent, parameters being passed, and other details.
  • Vary endpoints: Layer in various project endpoints. 
  • Switch between sandbox and production: Be sure you fully swap out the trial and production API keys wherever needed, as this will ensure that customers are only contacted via the production API integration.

Back to top

Benefits of Delighted's REST API

Integrating with the API will let you:

  • Automate sending and save time: Send without manually uploading a CSV or Excel file into Delighted.
  • Gather regular feedback: Maintain a constant pulse on customer sentiment by sending regularly.
  • Trigger sending at the ideal moment: Trigger surveys at the right time, like immediately post-purchase.
  • Achieve higher response rates: Send at times that boost response rates (like when a customer’s experience is fresh on their mind).
  • Sync feedback to your own systems: Get your data in a consistent format for storage in your other collection and reporting systems.

Back to top

Use case: Triggering surveys via the API

The most common reason that customers leverage the Delighted API is to send surveys.

Key request elements

The key elements of the sending to people API endpoint:

  • Request method: POST
  • Endpoint (sending to people): /v1/people.json
  • Endpoint (adding people to Autopilot): /v1/autopilot/email/memberships.json and /v1/autopilot/sms/memberships.json
  • Language: Delighted offers support for Curl, Ruby, Node.js, Python, and PHP. View sample request formats in our API documentation.

Breakdown of parameters

Sending to people endpoint

See the full endpoint documentation here. The parameters that you can pass to further refine requests:

  • email: Email address of the person being surveyed (required).
  • name: Name of the person being surveyed.
  • delay: Delay until a survey is sent (defaults to 0 seconds, sending surveys immediately).
  • properties: Metadata associated with each survey request. Examples include location, product purchased, or customer type.
  • locale: Language to send the survey in. All supported locales can be found in our API documentation, and more information about locales can be found in the Translating your Survey article.

Adding people to Autopilot endpoint

See the full endpoint documentation here. The parameters you can pass to add details about the new Autopilot member:

  • person_email: Email address of the person being surveyed (required for Email Autopilot).
  • person_phone_number: Phone number of the person being surveyed (required for SMS Autopilot).
  • person_name: Name of the person being surveyed.
  • properties: Metadata associated with each survey request. Examples include location, product purchased, or customer type.

Back to top

Use case: Exporting via the API

There are multiple types of data that you can export from Delighted using the REST API, including response data and engagement metrics.

Key request elements

  • Request method: GET
  • Endpoint (listing responses): /v1/survey_responses.json
  • Endpoint (listing engagement metrics): /v1/metrics.json
  • Language: Delighted offers support for Curl, Ruby, Node.js, Python, and PHP. You can view sample request formats in the API documentation.

Breakdown of parameters

Listing responses endpoint

Access the listing responses documentation here: https://delighted.com/docs/api/listing-survey-responses.

This endpoint will provide a list of all responses for your account. A few key parameters to consider including:

  • per_page: This parameter adjusts the number of responses shown per page. (Set to 20 by default.)
  • since and until: Both parameters will limit the time window used to list your responses.
  • expand: This is a key parameter to consider for revealing more information regarding each response. If you’re interested in showing the respondent’s name, be sure to pass “expand[]=person” to expand the Person object.

Listing metrics endpoint

This endpoint will provide requested engagement metrics from your account. Access the metrics documentation here: https://delighted.com/docs/api/getting-metrics. 

A few parameters to consider including:

  • since and until: Both parameters will limit the time window used to list your responses.
  • trend: Passing this parameter will generate your metrics for a specific trend. To find the value passed along with this parameter, simply copy the digits at the end of the trend’s URL string (ex. /trends/1234).

Back to top

How do I distinguish between projects when calling the API?

Each project has its own API key.

Just like when setting up other integrations, make sure you see the correct project name in the top left corner when grabbing the API key from the API documentation page to guarantee you’re connecting to the right one.

Back to top

Can I schedule a batch of surveys to be sent at different times?

Yes!

You can call our Sending to people endpoint multiple times for the same person, or you can use our Adding people to Autopilot endpoint to add a respondent to your recurring Autopilot schedule.

Back to top

Can I add or remove emails from Autopilot with the API?

Yes!

With the Autopilot API endpoints, you can get the current Autopilot configuration (on or off), list everyone currently in Autopilot, add/update Autopilot members, and remove Autopilot members. Read more on our Autopilot article or in the documentation for each endpoint.

Back to top

Can I generate a list of all the people I've surveyed?

Yes!

You can access our Listing people endpoint to export a list of all active people in your account, just as you’d see on the People tab. In this response, we’ll provide the last sent timestamp, last response timestamp, next scheduled send (if applicable), and a few other details about each person.

Back to top

Can I cancel a pending survey request?

Yes!

If the survey is scheduled to be sent at a future date, you can cancel the pending request via the Delete pending survey requests endpoint.

Back to top

Can I pass arrays via the API to assign property values?

No.

Delighted’s API does not currently accept arrays. We suggest passing each category that would otherwise be sent as an array as an individual boolean property (ex. Property A=True, Property B=False, Property C=True). This will allow you to pass through all those properties to filter different configurations within each individual category (ex. returning responses solely when Property A and Property C are set to True).

Back to top

If I've previously added someone to a project, what endpoint do I use to survey them again?

Each survey is dispatched based on a new survey request. To survey someone again, you can send another API request to our Sending to people endpoint.

Back to top

Does the throttle period apply to API requests?

Yes.

The throttle period applies across all platforms in a single project, including surveys scheduled via the API.

Back to top

Are there rate limits on how often I can ping the API?

Yes.

While occasional bursts are acceptable, we recommend a maximum of 100 requests per minute (100/min) on average. Otherwise, we may reach out to ensure optimal performance is maintained.

Back to top

Still need help? Contact Us Contact Us