Buttondown Survey Responses API

openapi: 3.2.0
info:
  title: Buttondown Survey Responses API
  version: 1.0.0
  description: The Buttondown API lets you manage newsletters, subscribers, emails, and more. See [the documentation](https://docs.buttondown.com/api-introduction) for guides and examples.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
- url: https://api.buttondown.com/v1
security:
- ApiKeyAuth: []
tags:
- name: Survey Responses
paths:
  /survey_responses:
    get:
      operationId: retrieve_survey_responses
      summary: Retrieve Survey Responses
      parameters:
      - in: query
        name: email_id
        schema:
          description: If provided, only return responses submitted from the given email ID(s).
          example:
          - em_01jv2m9q8r7s6t5w4x3y2z1abc
          title: Email Id
          items:
            maxLength: 50
            pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:em)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
            type: string
          type: array
        required: false
        description: If provided, only return responses submitted from the given email ID(s).
        example:
        - em_01jv2m9q8r7s6t5w4x3y2z1abc
      - in: query
        name: automation_id
        schema:
          description: If provided, only return responses submitted from the given automation ID(s).
          example:
          - aut_01jv2m9q8r7s6t5w4x3y2z1abc
          title: Automation Id
          items:
            maxLength: 50
            pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:aut)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
            type: string
          type: array
        required: false
        description: If provided, only return responses submitted from the given automation ID(s).
        example:
        - aut_01jv2m9q8r7s6t5w4x3y2z1abc
      - in: query
        name: subscriber_id
        schema:
          description: If provided, only return responses made by the given [subscriber(s)](https://docs.buttondown.com/api-subscribers-introduction).
          example:
          - sub_01jv2m9q8r7s6t5w4x3y2z1abc
          title: Subscriber Id
          items:
            maxLength: 50
            pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
            type: string
          type: array
        required: false
        description: If provided, only return responses made by the given [subscriber(s)](https://docs.buttondown.com/api-subscribers-introduction).
        example:
        - sub_01jv2m9q8r7s6t5w4x3y2z1abc
      - in: query
        name: source
        schema:
          description: If provided, only return responses submitted from the given arbitrary source string(s).
          example:
          - landing-page
          title: Source
          items:
            maxLength: 100
            minLength: 1
            type: string
          type: array
        required: false
        description: If provided, only return responses submitted from the given arbitrary source string(s).
        example:
        - landing-page
      - in: query
        name: survey_id
        schema:
          description: If provided, only return responses made to the given [survey(s)](https://docs.buttondown.com/api-surveys-introduction).
          example:
          - srv_01jv2m9q8r7s6t5w4x3y2z1abc
          title: Survey Id
          items:
            maxLength: 50
            pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:srv)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
            type: string
          type: array
        required: false
        description: If provided, only return responses made to the given [survey(s)](https://docs.buttondown.com/api-surveys-introduction).
        example:
        - srv_01jv2m9q8r7s6t5w4x3y2z1abc
      - in: query
        name: creation_date__start
        schema:
          description: If provided, only return responses made after the given date.
          title: Creation Date  Start
          format: date
          type: string
        required: false
        description: If provided, only return responses made after the given date.
      - in: query
        name: creation_date__end
        schema:
          description: If provided, only return responses made before the given date.
          title: Creation Date  End
          format: date
          type: string
        required: false
        description: If provided, only return responses made before the given date.
      - in: query
        name: expand
        schema:
          description: If provided, expand the given field.
          items:
            enum:
            - email
            - subscriber
            - survey
            - automation
            type: string
          title: Expand
          type: array
        required: false
        description: If provided, expand the given field.
      - in: query
        name: page
        required: false
        description: The page number of the paginated response.
        schema:
          type: integer
          title: Page
          description: The page number of the paginated response.
          default: 1
          example: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsePage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: List all survey responses
      tags:
      - Survey Responses
      security:
      - ApiKeyAuth: []
    post:
      operationId: create_survey_response
      summary: Create Survey Response
      parameters: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
          links:
            update_survey_response:
              operationId: update_survey_response
              parameters:
                path.id: $response.body#/id
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage_CreateSurveyResponseErrorCode_'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '409':
          description: Conflict
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Create a new survey response
      tags:
      - Survey Responses
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseInput'
        required: true
      security:
      - ApiKeyAuth: []
  /survey_responses/{id}:
    patch:
      operationId: update_survey_response
      summary: Update Survey Response
      parameters:
      - in: path
        name: id
        schema:
          title: Id
          type: string
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
          links: {}
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorMessage'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            X-RateLimit-Limit:
              description: Requests permitted per minute.
              schema:
                type: integer
            X-RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp at which the window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorMessage'
      description: Update a survey response's text. Only the response owner (subscriber) can update their response.
      tags:
      - Survey Responses
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResponseUpdateInput'
        required: true
      security:
      - ApiKeyAuth: []
components:
  schemas:
    FilterGroup:
      description: "Buttondown's filtering schema can be used for multiple things:\n\n- Filtering [the audience of an email](/api-emails-create) to a specific subset\n- Creating [finely-tuned automations](/api-automation-introduction)\n\nFilters are fractal; they can be nested in groups, and groups can be nested in other groups. This is accomplished through a tree-like structure. Every \"FilterGroup\" has a \"predicate\" field, which is either \"and\" or \"or\", which determines how the filters and groups within the group are combined, a \"groups\" field, which is a list of \"FilterGroup\" objects (that's that recursive bit!), and a \"filters\" field, which are the leaf-level filters themselves.\n\nLet's say you want a simple filter: all subscribers who have a tag whose ID is `sub_tag_0j6hb7h40j6hb7h40j6hb7h40j`. You can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}],\n    \"groups\": [],\n    \"predicate\": \"and\"\n}\n```\n\nNow, let's say you want to filter for subscribers who have that tag and a tag whose ID is `sub_tag_0j6hb7h40j6hb7h40j6hb7h40k`. You can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40k\"}],\n    \"groups\": [],\n    \"predicate\": \"and\"\n}\n```\n\nIf you wanted to change that `and` to an `or`, you can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40k\"}],\n    \"groups\": [],\n    \"predicate\": \"or\"\n}\n```\n\nNow, let's say you want to filter for subscribers who have the first tag _or_ both the second tag and a third tag whose ID is `sub_tag_0j6hb7h40j6hb7h40j6hb7h40m`. This is where the whole nested thing comes in handy. You can do that like this:\n\n```json\n{\n    \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"}],\n    \"groups\": [\n        {\n            \"filters\": [{\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40k\"}, {\"field\": \"subscriber.tags\", \"operator\": \"contains\", \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40m\"}],\n            \"groups\": [],\n            \"predicate\": \"and\"\n        }\n    ],\n    \"predicate\": \"or\"\n}\n```\n\nYou can read more about the specific filter construction in the [Filter documentation](/api-emails-filter)."
      properties:
        filters:
          description: The leaf-level filters to apply to the audience.
          items:
            $ref: '#/components/schemas/Filter'
          title: Filters
          type: array
        groups:
          description: The nested groups to apply to the audience.
          items:
            $ref: '#/components/schemas/FilterGroup'
          title: Groups
          type: array
        predicate:
          description: The logical operator to use when combining filters (either 'and' or 'or').
          enum:
          - and
          - or
          title: Predicate
          type: string
      required:
      - filters
      - groups
      - predicate
      title: FilterGroup
      type: object
    EmailCommentingMode:
      description: 'Governs who can comment on this email.


        This enum replaces the `is_comments_disabled` field, which has been deprecated. (Also note that this field may be superseded by newsletter-level settings; for instance, "enabled" is an invalid and inert value if the newsletter itself has comments disabled.)'
      enum:
      - disabled
      - enabled
      - enabled_for_paid_subscribers
      title: CommentingMode
      type: string
    ErrorMessage_CreateSurveyResponseErrorCode_:
      properties:
        code:
          allOf:
          - $ref: '#/components/schemas/CreateSurveyResponseErrorCode'
          description: The error code.
        detail:
          description: A human-readable description of the error.
          title: Detail
          type: string
        metadata:
          additionalProperties:
            type: string
          default: {}
          description: Additional context about the error. When present, a `documentation_url` key links to docs explaining how to resolve it.
          title: Metadata
          type: object
      required:
      - detail
      title: ErrorMessage[CreateSurveyResponseErrorCode]
      type: object
    ResponseInput:
      additionalProperties: false
      properties:
        subscriber_id:
          description: The subscriber who submitted the response.
          example:
          - sub_01jv2m9q8r7s6t5w4x3y2z1abc
          maxLength: 50
          pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:sub)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
          title: Subscriber Id
          type: string
        survey_id:
          description: The survey being answered.
          example:
          - srv_01jv2m9q8r7s6t5w4x3y2z1abc
          maxLength: 50
          pattern: ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|(?:srv)_(?:[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}|[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}))$
          title: Survey Id
          type: string
        email_id:
          description: The email ID, automation ID, or arbitrary source string where the survey was answered.
          example: em_01jv2m9q8r7s6t5w4x3y2z1abc
          maxLength: 100
          minLength: 1
          title: Email Id
          type: string
        answer:
          description: The 1-based index of the selected answer in the survey's `answers` list.
          example: 1
          minimum: 1
          title: Answer
          type: integer
      required:
      - subscriber_id
      - survey_id
      - email_id
      - answer
      title: ResponseInput
      type: object
    Response:
      properties:
        id:
          description: A unique TypeID associated with the object.
          title: Id
          type: string
        creation_date:
          description: The date and time at which the object was first created.
          format: date-time
          title: Creation Date
          type: string
        answer:
          description: The answer given to the survey.
          maxLength: 500
          title: Answer
          type: string
        text:
          description: Optional text included by the subscriber with the response. Subscribers are only prompted to supply a text response if the `is_freeform_response_enabled` field is set to `true` on the survey.
          title: Text
          type: string
        survey_id:
          description: The ID of the survey this response was submitted to.
          title: Survey Id
          type: string
        subscriber_id:
          description: The ID of the subscriber who submitted this response.
          title: Subscriber Id
          type: string
        email_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The ID of the email where this response was submitted, if any.
          title: Email Id
        automation_id:
          anyOf:
          - type: string
          - type: 'null'
          description: The ID of the automation where this response was submitted, if any.
          title: Automation Id
        source:
          anyOf:
          - type: string
          - type: 'null'
          description: For responses not tied to an email or automation, the origin the survey was answered from (e.g. a `transactional:*` template). Null otherwise.
          title: Source
        subscriber:
          anyOf:
          - $ref: '#/components/schemas/Subscriber'
          - type: 'null'
        survey:
          anyOf:
          - $ref: '#/components/schemas/Survey'
          - type: 'null'
        email:
          anyOf:
          - $ref: '#/components/schemas/Email'
          - type: 'null'
        automation:
          anyOf:
          - $ref: '#/components/schemas/Automation'
          - type: 'null'
      required:
      - id
      - creation_date
      - answer
      - text
      - survey_id
      - subscriber_id
      title: Response
      type: object
    AutomationStatus:
      enum:
      - active
      - inactive
      title: Status
      type: string
      description: An enumeration.
    EmailStatus:
      description: 'Represents the state of an email.


        No action is required to move from one state or another; Buttondown

        internally handles the transitions, and exposing the status is for

        observability purposes only.'
      enum:
      - draft
      - managed_by_rss
      - about_to_send
      - scheduled
      - in_flight
      - paused
      - deleted
      - errored
      - sent
      - imported
      - throttled
      - resending
      - transactional
      - suppressed
      title: Status
      type: string
    Filter:
      description: "A filter is a single condition that can be evaluated against a [Subscriber](/api-subscribers-retrieve). It has a field, an operator, and a value:\n\n```json\n{\n    \"field\": \"subscriber.tags\",\n    \"operator\": \"contains\",\n    \"value\": \"sub_tag_0j6hb7h40j6hb7h40j6hb7h40j\"\n}\n```\n\nThe field is the path to the field on the subscriber to evaluate. The operator is the operator to use when evaluating the filter. The value is the value to compare the field to. Tag filters require the tag's ID (either a UUID or TypeID), not its name."
      properties:
        field:
          title: Field
          type: string
        operator:
          $ref: '#/components/schemas/Operator'
        value:
          title: Value
          type: string
      required:
      - field
      - operator
      - value
      title: Filter
      type: object
    Action:
      description: An action to perform when the automation's trigger fires.
      properties:
        type:
          $ref: '#/components/schemas/AutomationActionType'
          description: The type of action to perform.
        metadata:
          additionalProperties: true
          description: Configuration specific to the action type.
          title: Metadata
          type: object
        timing:
          anyOf:
          - $ref: '#/components/schemas/Timing'
          - type: 'null'
          description: When to execute this action. Defaults to immediate if not specified.
      required:
      - type
      - metadata
      title: Action
      type: object
    SurveyInputType:
      enum:
      - radio
      - checkbox
      - text
      title: InputType
      type: string
      description: An enumeration.
    Operator:
      enum:
      - equals
      - not_equals
      - contains
      - not_contains
      - is_empty
      - is_not_empty
      - greater_than
      - less_than
      title: Operator
      type: string
      description: An enumeration.
    ValidationErrorMessage:
      properties:
        detail:
          description: A list of validation errors.
          items:
            $ref: '#/components/schemas/ValidationErrorDetail'
          title: Detail
          type: array
      required:
      - detail
      title: ValidationErrorMessage
      type: object
    FirewallReasonCode:
      enum:
      - email_address_capital_letters
      - email_address_cleantalk_score
      - email_address_contains_prohibited_string
      - email_address_domain_burst
      - email_address_esp_suppression
      - email_address_extant_subscriber_count
      - email_address_gmail_word_numbers
      - email_address_has_gravatar
      - email_address_is_honeypot
      - email_address_length
      - email_address_local_part_has_many_periods
      - email_address_many_consonants_in_a_row
      - email_address_mx_record_is_valid
      - email_address_noreply_local_part
      - email_address_null_characters
      - email_address_peaceful_domain
      - email_address_plus_single_number
      - email_address_plus_variant_accounts
      - email_address_previous_evaluation
      - email_address_prohibited_via_domain
      - email_address_regex
      - email_address_sandbox_test
      - email_address_shannon_entropy
      - email_address_tied_to_account
      - email_address_typo
      - embedded_form_honeypot
      - fingerprint_missing
      - ip_address_cleantalk_score
      - ip_address_country_risk
      - ip_address_datacenter
      - ip_address_extant_subscriber_count
      - ip_address_peaceful
      - ip_address_previous_evaluation
      - ip_address_prohibited
      - metadata_has_garbage
      - newsletter_age
      - newsletter_has_customized_transactional_email
      - newsletter_has_prohibited_string
      - newsletter_status
      - project_honeypot
      - referrer_url_prohibited
      - registration_without_prior_page_visit
      - subscriber_import_provenance
      - subscriber_import_source
      - text_contains_malicious_url
      - text_contains_prohibited_string
      - turnstile_response_token_is_valid
      - user_agent_known
      - username_shannon_entropy
      title: FirewallReasonCode
      type: string
      description: An enumeration.
    CreateSurveyResponseErrorCode:
      enum:
      - invalid_input
      title: CreateSurveyResponseErrorCode
      type: string
      description: An enumeration.
    Subscriber:
      description: 'Subscribers are the main way you collect email addresses and

        recipients on Buttondown. They''re what you see on your

        [subscribers page](https://buttondown.com/subscribers).


        Relevant changes to the schema:


        - [2024-08-01](https://docs.buttondown.com/api-changelog-2024-08-01): renamed `subscriber_type` and `email` to `type` and `email_address` respectively.

        - [2024-07-13](https://docs.buttondown.com/api-changelog-2024-08-01): removed `external_url` in favor of `absolute_url`.'
      properties:
        id:
          description: A unique TypeID associated with the object.
          title: Id
          type: string
        creation_date:
          description: The date and time at which the object was first created.
          format: date-time
          title: Creation Date
          type: string
        avatar_url:
          anyOf:
          - type: string
          - type: 'null'
          description: URL of the subscriber's avatar image (e.g. a Gravatar URL), if available.
          title: Avatar Url
        bounce_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: The date of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable.
          title: Bounce Date
        bounce_reason:
          anyOf:
          - $ref: '#/components/schemas/SubscriberUndeliverabilityReason'
          - type: 'null'
          description: The reason of the subscriber's most recent bounce event. May be set even if the subscriber has not yet been marked as undeliverable.
        churn_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When the subscriber cancelled their paid subscription, if applicable.
          title: Churn Date
        commenting_disabled:
          default: false
          description: Whether this subscriber is prevented from commenting.
          title: Commenting Disabled
          type: boolean
        country:
          anyOf:
          - type: string
          - type: 'null'
          description: The ISO 3166-1 alpha-2 country code inferred from the subscriber's IP address at signup, if available.
          example: US
          title: Country
        email_address:
          description: The email address of the subscriber.
          example: telemachus@buttondown.email
          title: Email Address
          type: string
        gift_subscription_end_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When the subscriber's gift subscription expires, if applicable.
          title: Gift Subscription End Date
        gift_subscription_message:
          anyOf:
          - type: string
          - type: 'null'
          description: A custom message that was sent to the subscriber when the gift subscription was created.
          title: Gift Subscription Message
        ip_address:
          anyOf:
          - type: string
          - type: 'null'
          description: The IP address recorded when the subscriber signed up, if available.
          title: Ip Address
        last_click_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When the subscriber most recently clicked a link in an email.
          title: Last Click Date
        last_open_date:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          description: When the subscriber most recently opened an email.
          title: Last Open Date
        delivered_count:
          anyOf:
          - type: integer
          - type: 'null'
          description: The number of distinct emails — both broadcasts and automation sends — delivered to this subscriber. Cached and refreshed periodically, so it may lag recent activity.
          example: 12
          title: Delivered Count
        open_count:
          anyOf:
          - type: integer
          - type: 'null'
          description: The subscriber's open count.
          example: 7
          title: Open Count
        clicked_count:
          anyOf:
          - type: integer
          - type: 'null'
          description: The subscriber's clicked count.
          example: 3
          title: Clicked Count
        open_rate:
          anyOf:
          - type: number
          - type: 'null'
          description: The subscriber's open rate, computed from engagement counts. Null if delivered_count is 0 or null.
          example: 0.5833
          title: Open Rate
        click_rate:
          anyOf:
          - type: number
          - type: 'null'
          description: The subscriber's click rate, computed from engagement counts. Null if delivered_count is 0 or null.
          example: 0.25
          title: Click Rate
        metadata:
          additionalProperties: true
          default: {}
          description: A structured key-value blob that you can use to store arbitrary data on the object. Metadata can be nested — you can store objects and arrays within your metadata. (You can [read more about metadata.](https://docs.buttondown.com/metadata))
          title: Metadata
          type: object
        notes:
          default: ''
          description: Any notes you want to attach to the subscriber. These are not publicly visible.
          title: Notes
          type: string
        purchased_by:
          anyOf:
          - type: string
          - type: 'null'
          description: The email address of the individual who purchased this subscription on behalf of the subscriber.
          title: Purchased By
        purchased_message:
          anyOf:
          - type: string
          - type: 'null'
          description: A custom message that was sent to the subscriber when the subscription was purchased on behalf of the subscriber.
          title: Purchased Message
        referral_code:
          description: The subscriber's unique referral code, used to attribute referred signups.
          title: Referral Code
          type: string
        referrer_url:
          default: ''
          description: The URL the subscriber was referred from (e.g. where they submitted the subscription form).
          title: Referrer Url
          type: string
        risk_score:
          anyOf:
          - ty

# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/buttondown/refs/heads/main/openapi/buttondown-survey-responses-api-openapi.yml