parcelLab Survey API

openapi: 3.2.0
info:
  title: parcelLab Survey API
  version: v4
  description: '# API Description


    ## Overview


    Use this API to interact with the parcelLab platform. It is currently in preview. For a reference of our current API, please refer to the API documentation.


    The API v4 allows for enhanced and more standardized interaction with our platform. It does however not yet cover all of the features of our v1/v2 APIs.


    ## Authentication


    Most endpoints in this API need authentication, unless otherwise stated. The authentication is done using the `Authorization` header with the value `Parcellab-API-Token `. You can generate the token in our portal, or ask our support team for one. The token needs to be base64 encoded together with the account ID, like: `base64encode(account_id:token)`. Here is an example of how to do it in Python:


    ```python

    import base64

    base64.b64encode(b''account_id:token'').decode(''utf-8'')

    ```


    ## Errors


    The API uses standard HTTP status codes to show the success or failure of a request. In case of an error, the response body will contain a JSON object with the following structure:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "error_code",

    "detail": "Error message.",

    "attr": "Optional additional information."

    }

    ]

    }

    ```


    ### 401 Unauthorized


    The API returns these errors with the status code 401 when the authentication fails. It also returns them when a request does not include the authentication information. Here are the 2 possible errors.


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "authentication_failed",

    "detail": "Incorrect authentication credentials.",

    "attr": null

    }

    ]

    }

    ```


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_authenticated",

    "detail": "Authentication credentials were not provided.",

    "attr": null

    }

    ]

    }

    ```


    ### 403 Forbidden


    The API returns this error when the authentication is correct but does not allow the request. For example, an API token with only the `read` scope gets this error on a POST. Here is how it looks:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "permission_denied",

    "detail": "You do not have permission to perform this action.",

    "attr": null

    }

    ]

    }

    ```


    ### 405 Method Not Allowed


    The API returns this error when you call an endpoint with an unexpected HTTP method. For example, if updating a user needs a POST request and you send a PATCH instead, you get this error. Here is how it looks:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "method_not_allowed",

    "detail": "Method “patch” not allowed.",

    "attr": null

    }

    ]

    }

    ```


    ### 406 Not Acceptable


    The API returns this error if you send an `Accept` header with a value other than `application/json`. Here is how the response would look:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_acceptable",

    "detail": "Could not satisfy the request Accept header.",

    "attr": null

    }

    ]

    }

    ```


    ### 415 Unsupported Media Type


    The API returns this error when the request content type is not JSON. Here is how the response would look:


    ```json

    {

    "type": "client_error",

    "errors": [

    {

    "code": "not_acceptable",

    "detail": "Unsupported media type “application/xml” in request.",

    "attr": null

    }

    ]

    }

    ```


    ### 500 Internal Server Error


    The API returns this error when the server encounters an unexpected error. Here is how the response would look:


    ```json

    {

    "type": "server_error",

    "errors": [

    {

    "code": "error",

    "detail": "A server error occurred.",

    "attr": null

    }

    ]

    }

    ```'
tags:
- name: Survey
paths:
  /v4/survey/survey/{id}/:
    get:
      operationId: survey_survey_retrieve
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this Survey.
        required: true
      tags:
      - Survey
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSurvey'
          description: ''
      summary: Survey survey retrieve
      x-summary-source: derived
  /v4/survey/survey/{id}/answer/:
    get:
      operationId: survey_survey_answer_retrieve
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this Survey.
        required: true
      - in: query
        name: ref_id
        schema:
          type: string
        required: true
      - in: query
        name: reference_type
        schema:
          type: string
          enum:
          - return_registration
          - tracking
      tags:
      - Survey
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSurvey'
          description: ''
      summary: Survey survey answer retrieve
      x-summary-source: derived
    post:
      operationId: survey_survey_answer_create
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this Survey.
        required: true
      tags:
      - Survey
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SurveyResponseRequest'
            examples:
              ValidExample:
                value:
                  data:
                    key: value
                  is_complete: true
                  reference_id: some_reference_id
                summary: Save a survey response
                description: This saves a survey response with completed result.
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SurveyResponseRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/SurveyResponseRequest'
        required: true
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponseResponse'
          description: ''
      summary: Survey survey answer create
      x-summary-source: derived
  /v4/survey/survey/themes/:
    get:
      operationId: survey_survey_themes_retrieve
      description: Retrieve common themes for surveys.
      parameters:
      - in: query
        name: default
        schema:
          type: boolean
      tags:
      - Survey
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400Response'
          description: ''
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyThemeResponse'
          description: ''
      summary: Survey survey themes retrieve
      x-summary-source: derived
components:
  schemas:
    SurveyThemeResponse:
      type: object
      description: Theming configuration applied to survey UI.
      properties:
        data:
          type: object
          description: A json object containing the survey theme.
      required:
      - data
    ErrorResponse404:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error404'
      required:
      - errors
      - type
    GenericErrorItem:
      type: object
      properties:
        code:
          type: string
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - code
      - detail
    SurveyResponseRequest:
      type: object
      description: 'Survey response with customer-submitted data.


        `reference_type` can be provided explicitly and defaults to server-side

        inference from `reference_id`.'
      properties:
        data:
          type: object
          description: A JSON object containing survey data.
        is_complete:
          type: boolean
        reference_id:
          type: string
          minLength: 1
          maxLength: 255
        reference_type:
          allOf:
          - $ref: '#/components/schemas/ReferenceTypeEnum'
          description: 'Optional reference type. If omitted, product-api infers the value from `reference_id`.


            * `tracking` - Tracking

            * `return_registration` - Return registration'
      required:
      - data
      - is_complete
      - reference_id
    PublicSurvey:
      type: object
      description: Read-only public view of a survey.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        emailPreviewCdn:
          type: string
          readOnly: true
        config:
          type: object
        name:
          type: string
          maxLength: 255
        status:
          $ref: '#/components/schemas/SurveyStatusEnum'
        archived:
          type: boolean
          title: Is archived
        type:
          $ref: '#/components/schemas/SurveyTypeChoices'
        surveyUrl:
          type: string
          description: Public URL to vote on the survey. Backend is responsible for replacing the ref_id.
          readOnly: true
        isEditable:
          type: boolean
          readOnly: true
      required:
      - emailPreviewCdn
      - id
      - isEditable
      - name
      - surveyUrl
    Error400Response:
      type: object
      properties:
        type:
          type: string
        errors:
          type: array
          items:
            $ref: '#/components/schemas/GenericErrorItem'
      required:
      - errors
      - type
    SurveyResponseResponse:
      type: object
      description: Envelope for survey response data returned from processing.
      properties:
        isComplete:
          type: boolean
        detail:
          type: string
      required:
      - detail
    SurveyTypeChoices:
      enum:
      - nps
      - smart_survey
      type: string
      description: '* `nps` - NPS

        * `smart_survey` - Smart Survey'
    ReferenceTypeEnum:
      enum:
      - tracking
      - return_registration
      type: string
      description: '* `tracking` - Tracking

        * `return_registration` - Return registration'
    ClientErrorEnum:
      enum:
      - client_error
      type: string
      description: '* `client_error` - Client Error'
    ErrorCode404Enum:
      enum:
      - not_found
      type: string
      description: '* `not_found` - Not Found'
    SurveyStatusEnum:
      enum:
      - draft
      - archived
      - published
      type: string
      description: '* `draft` - Draft Survey

        * `archived` - Archived Survey

        * `published` - Published Survey'
    Error404:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode404Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
  securitySchemes:
    HeaderToken:
      type: apiKey
      in: header
      name: Authorization
      x-gitbook-prefix: Parcellab-API-Token
      x-gitbook-token-placeholder: YOUR_BASE64_ENCODED_API_TOKEN
      description: 'Send `Authorization: Parcellab-API-Token <encoded-token>`.


        `<encoded-token>` = `base64(account_id:token)` as provided in the portal.'
    OAuth2Authentication:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Unbound access tokens use Authorization: Bearer <token>. DPoP-bound tokens use Authorization: DPoP <token> and a DPoP proof header signed with the bound key for each request. Supported proof algorithms: ES256 and RS256.'