Delighted People API
Manage people records for survey targeting
OpenAPI Specification
openapi: 3.0.3
info:
title: Delighted Autopilot People API
description: REST API for the Delighted customer satisfaction platform. Enables sending surveys, retrieving and adding survey responses, accessing NPS and CSAT metrics, managing Autopilot drip campaigns, handling webhooks for real-time events, and managing people records including unsubscribes and bounces. Authentication is via HTTP Basic Auth using per-project API keys.
version: v1
contact:
name: Delighted Support
url: https://app.delighted.com/docs/api
termsOfService: https://delighted.com/terms
license:
name: Proprietary
url: https://delighted.com/terms
servers:
- url: https://api.delighted.com/v1
description: Delighted API v1
security:
- basicAuth: []
tags:
- name: People
description: Manage people records for survey targeting
paths:
/people.json:
post:
operationId: sendToPersonOrCreatePerson
summary: Send survey to person
description: Creates or updates a person record and optionally schedules a survey to be sent to them. If the person already exists (matched by email or phone), their record is updated with any new properties.
tags:
- People
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SendToPersonRequest'
responses:
'200':
description: Person created or updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/PersonSurveyResponse'
'401':
description: Unauthorized - invalid or missing API key
'429':
description: Rate limit exceeded
headers:
Retry-After:
schema:
type: integer
description: Seconds to wait before retrying
get:
operationId: listPeople
summary: List people
description: Returns a paginated list of people in the project.
tags:
- People
parameters:
- name: per_page
in: query
description: Number of results per page. Default is 20, maximum is 100.
schema:
type: integer
default: 20
maximum: 100
- name: since
in: query
description: Unix timestamp to limit results to people created on or after this time.
schema:
type: integer
- name: until
in: query
description: Unix timestamp to limit results to people created on or before this time.
schema:
type: integer
- name: email
in: query
description: Restricts results to a specific person by email address.
schema:
type: string
format: email
- name: phone_number
in: query
description: Phone number in E.164 format (e.g. +17132746524).
schema:
type: string
responses:
'200':
description: List of people
headers:
Link:
schema:
type: string
description: Cursor-based pagination link for next page
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Person'
'401':
description: Unauthorized
'429':
description: Rate limit exceeded
/people/{person_identifier}:
delete:
operationId: deletePerson
summary: Delete person
description: Deletes the specified person and all information related to them, including surveys, responses, properties, Autopilot membership, survey history, integration links, unsubscribe/bounce status, and testimonials.
tags:
- People
parameters:
- name: person_identifier
in: path
required: true
description: Person identifier. Can be the person ID (e.g. 24248363), email prefixed with 'email:' (e.g. email:jony@appleseed.com), or phone number prefixed with 'phone_number:' (e.g. phone_number:+17132746524).
schema:
type: string
responses:
'202':
description: Person deletion accepted
content:
application/json:
schema:
$ref: '#/components/schemas/OkResponse'
'401':
description: Unauthorized
'404':
description: Person not found
'429':
description: Rate limit exceeded
/people/{person_email}/survey_requests/pending.json:
delete:
operationId: deletePendingSurveyRequests
summary: Delete pending survey requests
description: Removes all scheduled (not yet sent) survey requests for the specified person.
tags:
- People
parameters:
- name: person_email
in: path
required: true
description: Email of the person whose pending surveys should be deleted.
schema:
type: string
format: email
responses:
'200':
description: Pending surveys deleted successfully
content:
application/json:
schema:
$ref: '#/components/schemas/OkResponse'
'401':
description: Unauthorized
'404':
description: Person not found
'429':
description: Rate limit exceeded
components:
schemas:
OkResponse:
type: object
description: Simple success response.
properties:
ok:
type: boolean
description: Indicates the operation was successful.
example: true
PersonSurveyResponse:
type: object
description: Response after sending survey to or creating a person.
properties:
id:
type: string
description: Unique person identifier.
email:
type: string
format: email
description: Person's email address.
name:
type: string
nullable: true
description: Person's name.
survey_scheduled_at:
type: integer
description: Unix timestamp when the survey is scheduled to be sent.
properties:
type: object
additionalProperties:
type: string
description: Custom properties associated with the person.
SendToPersonRequest:
type: object
description: Request body for sending a survey to a person.
properties:
email:
type: string
format: email
description: Email of the person. Required if phone_number is not provided or channel is email.
phone_number:
type: string
description: Contact number in E.164 format. Required if channel is sms.
channel:
type: string
enum:
- email
- sms
description: Survey delivery method. Defaults to email.
name:
type: string
description: Person's name.
delay:
type: integer
description: Seconds to wait before sending the survey. Default is 0.
properties:
type: object
additionalProperties:
type: string
description: 'Custom metadata fields for segmentation and integration. Supports special keys: question_product_name, delighted_email_subject, delighted_intro_message, locale, thank_you_message, thank_you_link_text, thank_you_link_url.'
send:
type: boolean
description: Set false to create person without sending a survey. Default is true.
default: true
last_sent_at:
type: integer
description: Unix timestamp for survey throttling consideration. Used when syncing historical send data.
email_update:
type: string
format: email
description: New email address when updating an existing contact.
phone_number_update:
type: string
description: New phone number when updating an existing contact.
Person:
type: object
description: A person record in the Delighted project.
properties:
id:
type: string
description: Unique person identifier.
email:
type: string
format: email
description: Person's email address.
name:
type: string
nullable: true
description: Person's name.
created_at:
type: integer
description: Unix timestamp when the person was created.
phone_number:
type: string
nullable: true
description: Person's phone number in E.164 format.
last_sent_at:
type: integer
nullable: true
description: Unix timestamp when the last survey was sent.
last_responded_at:
type: integer
nullable: true
description: Unix timestamp when the person last responded to a survey.
next_survey_scheduled_at:
type: integer
nullable: true
description: Unix timestamp when the next survey is scheduled to be sent.
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Use your Delighted API key as the username. Leave the password empty. The API key is found in your project settings.