openapi.yaml

openapi: 3.0.0
info:
  version: 'v1'
  title: CloseAlert Reporting API
  description: |
    # Introduction
    The CloseAlert Reporting API can be used to import CloseAlert feedback into proprietary systems.
    The API is only available over the **HTTPS** protocol with the `api.closealert.com` domain.
    This API is RESTful and will only return JSON.

    # Authentication
    For authentication you must use a JSON WEB Token [JWT] ([RFC7519](https://tools.ietf.org/html/rfc7519)),
    which can only be generated from the CloseAlert application. To generate such a token please follow these steps:
    - 1. Go to your [CloseAlert application](https://app.closealert.com/) -> **Settings** -> **API Access**
    - 2. Select **Generate API Access Token**
    - 3. Fill out name
    - 4. Fill out how many days the token must be valid.
      - 14 and 7 days prior to expiration of the token you will receive an e-mail to remind you to create a new token.
    - 4. Copy the generated token and save it in a secure place. **Note**: This key is only provided once and not stored anywhere else.

    You must use the generated JWT for each request by sending it along with the **Authentication header**.
    For example, if your JWT is `super.safe.token`, you must add the following header to each request: *-H Authorization: Bearer super.safe.token'*

    ## IP Whitelisting
    For authentication to work, you will need to whitelist your servers' IP addresses from which the requests to our servers are sent. To whitelist IP addresses, please follow these steps:
    - 1. Go to your [CloseAlert application](https://app.closealert.com/) -> **Settings** -> **API Access**
    - 2. Scroll to **Whitelisted IP's**
    - 3. Add your IP address(es). **Note:** Without any IP addresses set, the API is not accessible.

    # Ratelimiting
    In order to provide a consistently high quality of service across the board we may limit requests.
    For this the [token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) is used.
    When receiving responses with status code `429`, please wait a few minutes and send additional requests again.
    In the meta data of the requests you can see how many requests are left in the `requests_left` attribute.

    # Limitations & Pagination
    To prevent our servers from overloading, the maximum data date-range is 1 month.
    Further, the number of results per request is capped at a maximum of 250.
    Should not all required data be retuned at once, use the `meta` object sent along with each request.
    This wil give you info on results and pages available within given filters.
    Alternatively use the links object. This will contains URLs with the same filters for the first, next, previous and last page.

tags:
  - name: 'form_responses'
servers:
  - url: 'https://api.closealert.com/v1/'
    description: Production Server
  # - url: 'https://api.closealert-staging.com/v1/'
  #   description: Staging Server
  # - url: 'http://api.closealert.local:8080/v1/'
  #   description: Local Server

paths:
  /{project_key}/form_responses:
    parameters:
    - in: path
      name: project_key
      required: true
      schema:
        type: string
      description: the key of your project
      example: e.g. 'company.com'
    get:
      tags:
        - form_responses
      security:
        - bearerAuth: []
      description: >
        Returns responses from CloseAlert that are received. Sorted on 'created_at' in ascending order
      parameters:
        - name: form_id
          in: query
          description: |
            To filter on a specific form. You can get a specific form_id by going to your [CloseAlert application](https://app.closealert.com/)
            -> **Forms** and select the form you want to filter on. You will now see the **form_id** in the url between **edit/** and **/questions**
          required: false
          style: form
          schema:
            type: integer
        - name: since
          in: query
          description: Responses received **since** a specific date-time ([ISO8601](https://en.wikipedia.org/wiki/ISO_8601))
          example: '2018-12-12T09:35:05+00:00'
          required: false
          style: form
          schema:
            type: string
            format: date-time
            default: 7 days ago
        - name: until
          in: query
          description: Responses received **until** a specific date-time ([ISO8601](https://en.wikipedia.org/wiki/ISO_8601))
          example: '2018-12-12T09:35:05+00:00'
          required: false
          style: form
          schema:
            type: string
            format: date-time
            default: 7 days after the **since** parameter
        - name: per_page
          in: query
          description: Maximum results per page
          example: 20
          required: false
          style: form
          schema:
            type: integer
            default: 100
        - name: page
          in: query
          description: The page number
          example: 1
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  form_responses:
                    type: array
                    items:
                      $ref: "#/components/schemas/form_response"
                  meta:
                    $ref: "#/components/schemas/meta"
                example:
                  form_responses:
                    - id: 1
                      created_at: '2014-03-17T17:22:10'
                      email: 'peter@closealert.com'
                      mail_url: 'http://www.closealert.com'
                      user_agent: 'Mozilla/5.0 (Intel Mac OS X 10.9'
                      device_type: 'desktop'
                      operating_system: 'macos'
                      followed_up: true
                      merge_tags:
                        age: 10
                        gender: male
                      form:
                        id: 34
                        form_type: email-satisfaction,
                        name: 'Email satisfaction form'
                      mailing:
                        id: 42
                        name: 'Email satisfaction mailing'
                      group:
                        id: 44
                        name: 'Email satisfaction group'
                      answers:
                        - question: 'What do you think of this email?'
                          question_type: 'sentiment'
                          answer_type: null
                          question_index: '1'
                          response_value: 1
                        - question: 'Why are you positive?'
                          question_type: 'comment'
                          answer_type: null
                          question_index: '2'
                          response_value: 'I love the articles in this email'
                        - question: 'Can we have your info?'
                          question_type: 'form'
                          answer_type: 'email'
                          question_index: '3.1'
                          response_value: 'customer@provider.com'
                  meta:
                    page: 0
                    per_page: 100
                    total_pages: 2
                    total_results: 23
                    filters:
                      form_id: null
                      since: '2019-01-15T17:22:10'
                      until: '2019-01-23T17:22:10'
                    requests_left: 56
                  links:
                    first: https://api.closealert.com/v1/form_responses?page=0
                    last: https://api.closealert.com/v1/form_responses?page=1
                    next: https://api.closealert.com/v1/form_responses?page=1
                    prev: null
        '403':
          description: Authentication failed
        '422':
          description: Validation failed
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    $ref: "#/components/schemas/error"
                example:
                  error:
                    description: "Validation failed"
                    code: 422
                    attributes:
                      date_from: invalid filter
        '429':
          description: Too many requests
        '504':
          description: Took server too long to respond

components:
  schemas:
    form_response:
      properties:
        id:
          type: integer
          description: the form_response id
        created_at:
          type: string
          format: date-time
          description: the time stamp (ISO8601) this form_response was received
        email:
          type: string
          description: the respondent email address
        mail_url:
          type: string
          description: the respondent mail_url
        user_agent:
          type: string
          description: the respondent user agent
        device_type:
          type: string
          description: the respondent device type, tablet or desktop)
        operating_system:
          type: string
          description: the respondent operating system (macos, ios, windows, linux, android, or other)
        followed_up:
          type: boolean
          description: whether a follow up mail was sent from CloseAlert based on given answers
        merge_tags:
          type: object
          description: the merge tags that were send by the ESP
        form:
          type: object
          description: the form this response was received on
          properties:
            id:
              type: integer
              description: the form id
            form_type:
              type: string
              description: the type of form the response was received on
            name:
              type: string
              description: the form name
        mailing:
          type: object
          description: the mailing this response was received on
          properties:
            id:
              type: integer
              description: the id of the mailing
            name:
              type: string
              description: the name of the mailing
        group:
          type: object
          description: the group the mailing is in (either direct or nested)
          properties:
            id:
              type: integer
              description: the id of the group
            name:
              type: string
              description: the name of the group
        answers:
          type: array
          description: the respondent answers, sorted on question_index, ascending order
          items:
            type: object
            description: answer object
            properties:
              question:
                type: string
                description: the question that was asked
              question_type:
                type: string
                description: the type of the question
              question_index:
                type: string
                description: The index of the question on received form
              response_value:
                type: string
                description: The respondent's answer to this question
              answer_type:
                type: string
                description: The answer type
    meta:
      properties:
        page:
          type: integer
          description: The page number
        per_page:
          type: integer
          description: Maximum results per page
        total_pages:
          type: integer
          description: The total number of pages
        total_results:
          type: integer
          description: The total number of results
        filters:
          type: object
          description: The used filters for this request
          properties:
            form_id:
              type: integer
              description: The form_id that was filtered
            since:
              type: string
              description: The since-filter as time stamp (ISO8601)
            until:
              type: string
              description: The since-filter as time stamp (ISO8601)
    links:
      properties:
        first:
          type: string
          description: The link of the first page of results with current filters
        last:
          type: string
          description: The link of the last page of results with current filters
        next:
          type: string
          description: The link of the next page of results with current filters, will be `null` if it doesn't exist
        prev:
          type: string
          description: The link of the first page of results with current filters, will be `null` if it doesn't exist
    error:
      properties:
        description:
          type: string
          description: The description of the error
        code:
          type: integer
          description: The error code
        attributes:
          type: object
          description: An object containing key-value pairs with key=attribute, value=description of error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
security:
  - bearerAuth: []