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.