AskNicely Responses API

openapi: 3.2.0
info:
  title: AskNicely Responses API
  version: v1
  summary: Contact, survey-trigger, response, statistics and privacy operations for the AskNicely customer-experience (NPS/CSAT/5-Star) platform.
  description: 'The AskNicely API is a RESTful, JSON-returning API for importing contacts, triggering NPS/CSAT/5-Star surveys, retrieving survey responses and statistics, and honouring privacy (GDPR) deletion requests. Every AskNicely account is provisioned its own subdomain (`https://{domain}.asknice.ly`) and the API is served from that tenant host under `/api/v1`. Authentication is a single account API key supplied in the `X-apikey` request header (per-user keys; create a new user to isolate API traffic).


    This document was assembled by API Evangelist from AskNicely''s own public API reference at https://demo.asknice.ly/help/apidocs — one page per endpoint. Paths, methods, parameter names, examples and response bodies are transcribed from those pages; nothing has been invented. AskNicely does not publish an OpenAPI/Swagger document of its own.'
  termsOfService: https://www.asknicely.com/terms
  contact:
    name: AskNicely Support
    email: support@asknice.ly
    url: https://asknicely.zendesk.com/hc/en-us
  x-source: https://demo.asknice.ly/help/apidocs
  x-generated-by: API Evangelist enrichment pipeline
servers:
- url: https://{domain}.asknice.ly/api/v1
  description: Per-tenant AskNicely API host. Replace {domain} with your AskNicely subdomain.
  variables:
    domain:
      default: demo
      description: Your AskNicely account subdomain (the value in https://{domain}.asknice.ly).
security:
- apiKeyAuth: []
tags:
- name: Responses
  description: Retrieve survey responses.
paths:
  /responses/{sortDirection}/{pagesize}/{pagenumber}/{sinceTime}/{format}:
    get:
      operationId: getResponses
      tags:
      - Responses
      summary: Get survey responses
      description: Retrieves detailed survey responses. Up to 50,000 responses may be requested per call; make multiple calls to page through more. Requests above the redirect threshold are redirected to a temporary file on S3, so the calling client MUST follow redirects. The published path template also accepts three further optional trailing segments — `/{filter}/{sort_by}/{end_time}` — where `filter` is one of `answered`, `raw` or `published`, `sort_by` is `sent` or `responded`, and `end_time` is a unix timestamp upper bound. `question_type` in each row indicates whether the response was to an NPS, CSAT or 5STAR survey.
      x-source: https://demo.asknice.ly/help/apidocs/responses
      parameters:
      - name: sortDirection
        in: path
        required: true
        description: Sort direction. Defaults to `asc`.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      - name: pagesize
        in: path
        required: true
        description: Rows per request. Default and maximum are both 50,000.
        schema:
          type: integer
          maximum: 50000
          default: 50000
      - name: pagenumber
        in: path
        required: true
        description: Current page, starting at 1.
        schema:
          type: integer
          minimum: 1
      - name: sinceTime
        in: path
        required: true
        description: Unix timestamp; return responses at or after this time.
        schema:
          type: integer
      - name: format
        in: path
        required: true
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - csv
          default: json
      - name: includestatustime
        in: query
        required: false
        description: Set to `yes` to also return the unix-timestamp `case_closed_time` for each response.
        schema:
          type: string
          enum:
          - true
      - name: filters[]
        in: query
        required: false
        description: Custom data field to filter on (repeatable). Must be paired positionally with `values[]`; the number and order of filters and values must match.
        schema:
          type: array
          items:
            type: string
      - name: values[]
        in: query
        required: false
        description: Value for the correspondingly-positioned `filters[]` entry (repeatable).
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: A page of survey responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponsesEnvelope'
              example:
                success: true
                total: '10395'
                totalpages: '2079'
                pagenumber: '1'
                pagesize: '5'
                since_time: '0'
                end_time: '1642981569'
                data:
                - response_id: '54120'
                  person_id: '54121'
                  contact_id: '54121'
                  name: Aiman Shakeel
                  email: 3d2c555c.39829842@example.com
                  answer: '8'
                  answerlabel: '8'
                  data: null
                  comment: ''
                  note: null
                  status: ''
                  dontcontact: null
                  sent: '1614192119'
                  opened: '1614192119'
                  responded: '1614192119'
                  lastemailed: '1614192119'
                  created: '1614192119'
                  segment: null
                  question_type: nps
                  published: ''
                  publishedname: ''
            text/csv:
              schema:
                type: string
        '302':
          description: Redirect to a temporary S3 file holding the result set. Clients must follow redirects.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  schemas:
    SurveyResponse:
      type: object
      properties:
        response_id:
          type: string
        person_id:
          type: string
          description: Deprecated alias of contact_id.
        contact_id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        answer:
          type: string
          description: The score given.
        answerlabel:
          type: string
        comment:
          type: string
        note:
          type:
          - string
          - 'null'
        status:
          type: string
        dontcontact:
          type:
          - string
          - 'null'
        sent:
          type: string
          description: Unix timestamp.
        opened:
          type: string
          description: Unix timestamp.
        responded:
          type: string
          description: Unix timestamp.
        lastemailed:
          type: string
          description: Unix timestamp.
        created:
          type: string
          description: Unix timestamp.
        segment:
          type:
          - string
          - 'null'
        question_type:
          type: string
          description: nps, csat or fivestar.
        published:
          type: string
        publishedname:
          type: string
        case_closed_time:
          type: string
          description: Returned when includestatustime=yes.
      additionalProperties: true
    RateLimitError:
      allOf:
      - $ref: '#/components/schemas/ErrorEnvelope'
      - type: object
        properties:
          type:
            type: string
            description: Which window was exceeded, e.g. req-10s or req-60s.
          count:
            type: integer
            description: Requests made in the window.
          limit:
            type: integer
            description: Requests permitted in the window.
    ResponsesEnvelope:
      type: object
      properties:
        success:
          type: boolean
        total:
          type: string
        totalpages:
          type: string
        pagenumber:
          type: string
        pagesize:
          type: string
        since_time:
          type: string
        end_time:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/SurveyResponse'
    ErrorEnvelope:
      type: object
      description: The AskNicely error envelope. Not RFC 9457 Problem Details.
      properties:
        success:
          type: boolean
          const: false
        msg:
          type: string
          description: Human-readable error message.
      required:
      - success
      - msg
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
          example:
            success: false
            msg: We could not find the api key, or it was not set []
    RateLimited:
      description: Rate limit exceeded. `RateLimit-Req10s-*` and `RateLimit-Req60s-*` response headers report the current window, and `Retry-After` indicates when to retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
        RateLimit-Req10s-Limit:
          description: Requests permitted in the rolling 10-second window.
          schema:
            type: integer
        RateLimit-Req10s-Remaining:
          description: Requests remaining in the rolling 10-second window.
          schema:
            type: integer
        RateLimit-Req60s-Limit:
          description: Requests permitted in the rolling 60-second window.
          schema:
            type: integer
        RateLimit-Req60s-Remaining:
          description: Requests remaining in the rolling 60-second window.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/RateLimitError'
          example:
            success: false
            msg: 'Rate limit hit: reduce the rate of requests and retry'
            type: req-10s
            count: 201
            limit: 200
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-apikey
      description: The account API key, found in-platform under Settings > API. Every AskNicely user is issued their own key; create a separate user to isolate API traffic. Sending an invalid or missing key returns HTTP 401.