openapi: 3.2.0
info:
  version: 1.0.0
  title: Paperform Partial Submissions API
  contact:
    name: Paperform API Support
    url: https://paperform.co
    email: support@paperform.co
servers:
- url: https://api.paperform.co/v1
security:
- bearerAuth: []
tags:
- name: Partial Submissions
paths:
  /forms/{slug_or_id}/partial-submissions:
    get:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/skip'
      - $ref: '#/components/parameters/afterId'
      - $ref: '#/components/parameters/beforeId'
      - $ref: '#/components/parameters/beforeDate'
      - $ref: '#/components/parameters/afterDate'
      - $ref: '#/components/parameters/sort'
      description: This endpoint returns a list of partial submissions for a form matching the requested parameters. This feature is available as part of the Standard API.
      operationId: listFormPartialSubmissions
      tags:
      - Partial Submissions
      responses:
        '200':
          description: Successfully returned a list of partial submissions
          content:
            application/json:
              schema:
                type: object
                allOf:
                - properties:
                    status:
                      type: string
                      enum:
                      - ok
                    results:
                      type: object
                      properties:
                        partial-submissions:
                          type: array
                          items:
                            $ref: '#/components/schemas/PartialSubmission'
                - $ref: '#/components/schemas/Pagination'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/Validation'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: List form partial submissions
      x-summary-source: derived
  /forms/{slug_or_id}/partial-submissions/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/uuid'
      description: This endpoint returns a specific partial submission by ID. This feature is available as part of the Standard API.
      operationId: getFormPartialSubmission
      tags:
      - Partial Submissions
      responses:
        '200':
          description: 'Successfully returned a single partial submission that matched the provided ID

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      partial-submission:
                        $ref: '#/components/schemas/PartialSubmission'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Get form partial submission
      x-summary-source: derived
    delete:
      parameters:
      - $ref: '#/components/parameters/slugOrID'
      - $ref: '#/components/parameters/uuid'
      description: This endpoint deletes a specific partial submission by ID. This feature is available as part of the Standard API.
      operationId: deleteFormPartialSubmission
      tags:
      - Partial Submissions
      responses:
        '200':
          description: 'Successfully deleted a single partial submission that matched the provided ID

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Delete form partial submission
      x-summary-source: derived
  /partial-submissions/{id}:
    get:
      parameters:
      - $ref: '#/components/parameters/uuid'
      description: This endpoint returns a specific partial submission by ID. This feature is available as part of the Standard API.
      operationId: getPartialSubmission
      tags:
      - Partial Submissions
      responses:
        '200':
          description: 'Successfully returned a single partial submission that matched the provided ID

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                  results:
                    type: object
                    properties:
                      partial-submission:
                        $ref: '#/components/schemas/PartialSubmission'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Get partial submission
      x-summary-source: derived
    delete:
      parameters:
      - $ref: '#/components/parameters/uuid'
      description: This endpoint deletes a specific partial submission by ID. This feature is available as part of the Standard API.
      operationId: deletePartialSubmission
      tags:
      - Partial Submissions
      responses:
        '200':
          description: 'Successfully deleted a single partial submission that matched the provided ID

            '
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/Throttled'
        5XX:
          $ref: '#/components/responses/Unexpected'
      summary: Delete partial submission
      x-summary-source: derived
components:
  schemas:
    PartialSubmission:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the Partial Submission.
          example: 5d40fdaf174b4c0007043072
          readOnly: true
        form_id:
          type: string
          format: uuid
          description: The id of the Form for the Partial Submission.
          example: 5d40fdaf174b4c0007043072
          readOnly: true
        data:
          $ref: '#/components/schemas/SubmissionData'
        last_answered:
          type:
          - string
          - 'null'
        submitted_at:
          type:
          - string
          - 'null'
          format: date-string
          description: If the partial submission was submitted, this will be set to a formatted date-time string in your account timezone indicating the time the submission was made.
          readOnly: true
          example: '2019-04-14T09:00:00.000Z'
        updated_at:
          type: string
          description: A formatted date-time string in your account timezone indicating the last time the partial submission was updated.
          readOnly: true
          example: '2019-04-14T09:00:00.000Z'
        created_at:
          type: string
          description: A formatted date-time string in your account timezone indicating the time the partial submission was created.
          readOnly: true
          example: '2019-04-14T09:00:00.000Z'
        account_timezone:
          type: string
          description: The configured timezone for your account.
          readOnly: true
          example: America/New_York
        submitted_at_utc:
          type: string
          format: date-time
          description: A formatted date-time string in UTC indicating the time the form was created.
          readOnly: true
          example: '2019-04-14T09:00:00.000Z'
        created_at_utc:
          type: string
          format: date-time
          description: A formatted date-time string in UTC indicating the time the form was created.
          readOnly: true
          example: '2019-04-14T09:00:00.000Z'
        updated_at_utc:
          type: string
          format: date-time
          description: A formatted date-time string in UTC indicating the time the form was created.
          readOnly: true
          example: '2019-04-14T09:00:00.000Z'
    SubmissionData:
      type: object
      description: The `data` object stores the answers from the form. Each value is stored against it's key. Note that custom keys are not used here.
      properties:
        KEY:
          oneOf:
          - type: string
          - type: number
          - type: array
            items:
              oneOf:
              - type: string
              - type: object
          - type: object
          - type: boolean
    Pagination:
      type: object
      properties:
        total:
          type: integer
          description: The total number of items.
          readOnly: true
          example: 57
        has_more:
          description: Whether there are more items.
          type: boolean
          example: true
          readOnly: true
        limit:
          description: The limit of items per page.
          type: integer
          example: 20
          default: 20
        skip:
          description: The number of items to skip.
          type: integer
          default: 0
          example: 0
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
          example: error
        message:
          type: string
          description: An error message.
          example: Invalid request
        details:
          type: array
          description: Suggested actions to resolve the error.
          items:
            type: string
  responses:
    Throttled:
      description: Too Many Requests
      content:
        text/html:
          schema:
            type: string
            enum:
            - Too many requests.
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - authentication
                  description: Token not provided for not valid.
    Forbidden:
      description: Not Permitted
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - permission
                  description: Not permitted to access requested resource.
    Validation:
      description: Validation Error
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - validation
                  description: Invalid parameters provided.
    BadRequest:
      description: Invalid Request
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - validation
                  description: Invalid parameters provided.
    Unexpected:
      description: Unexpected Error
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - server_error
                  description: An unexpected error.
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            allOf:
            - $ref: '#/components/schemas/Error'
            - properties:
                error_type:
                  type: string
                  enum:
                  - not_found
                  description: The requested resource was not found.
  parameters:
    slugOrID:
      in: path
      name: slug_or_id
      required: true
      schema:
        type: string
      description: The form's slug, custom slug or ID.
      example: my-form-slug
    beforeDate:
      in: query
      name: before_date
      schema:
        type: string
        format: date-time
      description: Return results created on or after this date-time (UTC). Overwritten by `before_id`.
      example: '2019-06-11T20:36:29Z'
    afterDate:
      in: query
      name: after_date
      schema:
        type: string
        format: date-time
      description: Return results created before this date (UTC). Overwritten by `after_id`.
      example: '2019-06-11T20:36:29Z'
    uuid:
      in: path
      name: id
      required: true
      schema:
        type: string
        format: uuid
      description: The id of the record to get.
      example: 5d40fdaf174b4c0007043072
    skip:
      in: query
      name: skip
      schema:
        type: integer
        default: 0
      description: Number of results to skip in the result set.
    sort:
      in: query
      name: sort
      schema:
        type: string
        enum:
        - ASC
        - DESC
        default: DESC
      description: The direction to sort in. Results are sorted by `created_at`, and defaults to `"DESC"`.
      example: ASC
    limit:
      in: query
      name: limit
      schema:
        type: integer
        maximum: 100
        default: 20
      description: The number or results to return.
    afterId:
      in: query
      name: after_id
      schema:
        type: string
      description: Return results after the provided ID.
      example: 5d40fdaf174b4c0007043072
    beforeId:
      in: query
      name: before_id
      schema:
        type: string
      description: Return results before the provided ID.
      example: 5d40fdaf174b4c0007043072
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
x-readme:
  explorer-enabled: true
  proxy-enabled: true