openapi: 3.1.0
# Published on the public docs site, as a reference page and as this file.
# A contract without this key is internal.
x-docs-visibility: public
info:
  title: Assessor.io API v2 (public) - Submissions and Exports
  version: 1.6.0
  description: |
    Read assessment submissions for a campaign, and generate a full answer
    export inline.

    1.2.0 ADDED unitKey, ADDITIVELY, to both doors: the list DTO gains
    an optional unitKey, and the export's Submissions sheet gains a unitKey
    column beside participantId. It names the unit INSTANCE a submission
    belongs to, which is what an organisation- or department-level analysis
    groups by. Nothing was removed or renamed, and a client that ignores the
    field reads exactly what it read before.

    1.1.0 CHANGED THE LIST'S DEFAULT POPULATION. Both doors of this
    spec now default to the same rows: completed and reopened submissions, no
    in-progress drafts. The list used to return every row, so its unfiltered
    meta.total was larger than the export's rowCounts.submissions for the same
    campaign. DEPRECATED, NOT REMOVED: pass includeDrafts=1 to get the old
    population back in one call, or ?status=in_progress for the drafts alone.
    The Public API (v2) guide on docs.assessor.io describes the change.

    Answer content is gated separately from submission metadata. The list
    endpoint needs submissions:read and returns answers ONLY when the token
    additionally holds submissions:read:answers, so a metadata-only token can
    watch completion without ever seeing responses. The export endpoint is a
    different gate: results:export always produces a file containing the real
    answers, so provision it deliberately.

    AUDITOR REVIEW DATA IS SCOPED SEPARATELY AGAIN. An export always applies the
    auditor's corrections - withholding them would hand an integrator numbers
    that disagree with the scorecard the client is reading - but the verdicts,
    reviewer keys, per-answer review columns and auditor notes are disclosed
    only to a token that ALSO holds submissions:read:answers.
    export.reviewsIncluded says which of the two files you received.
servers:
  - url: /
security:
  - serviceToken: []
tags:
  - name: PublicSubmissions
paths:
  /api/v2/public/accounts/{accountId}/campaigns/{campaignId}/submissions:
    get:
      tags: [PublicSubmissions]
      operationId: v2ListSubmissions
      summary: List a campaign's assessment submissions.
      description: |
        Paginated. Filters are applied in-process and combine with AND.
        meta.answersIncluded reports whether the answers property was populated
        for this caller. Scope submissions:read (+ submissions:read:answers for
        answer content).

        POPULATION (changed in 1.1.0): completed and reopened
        submissions. In-progress drafts are excluded from BOTH the rows and
        meta.total, which is the population the export produces, so the two
        endpoints no longer answer "how many submissions" with different
        numbers. meta.draftsExcluded reports how many rows the default left
        out, counted after the other filters.

        TWO WAYS BACK TO THE OLD ROWS. An explicit ?status= names the
        population and WINS over the default - ?status=in_progress is still
        exactly the drafts - and includeDrafts=1 restores the whole
        draft-inclusive listing in one call. A client that was reading the
        unfiltered total as a completion count was reading the wrong number and
        should keep the new default.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/CampaignId'
        - name: assessmentId
          in: query
          required: false
          description: Restrict to one assessment within the campaign.
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Exact-match lifecycle status. Submissions with no stored status are treated as completed.
          schema:
            $ref: '#/components/schemas/SubmissionStatus'
        - name: submittedFrom
          in: query
          required: false
          description: Inclusive lower bound on submittedAt, epoch milliseconds. Non-numeric values are ignored.
          schema:
            type: integer
        - name: submittedTo
          in: query
          required: false
          description: Inclusive upper bound on submittedAt, epoch milliseconds. Non-numeric values are ignored.
          schema:
            type: integer
        - name: includeDrafts
          in: query
          required: false
          description: |
            Added in 1.1.0. Pass 1 or true to include in-progress drafts, the
            population this endpoint returned before 1.1.0. Anything else -
            including an absent parameter and including the string false -
            keeps the default, because a query string carries no booleans and
            treating every non-empty value as true would ship half-typed
            autosaves as data. Ignored when ?status= is present: an explicit
            status already names the population.
          schema:
            type: string
            enum: ['1', 'true']
        - $ref: '../components/v2-common.yaml#/components/parameters/Page'
        - $ref: '../components/v2-common.yaml#/components/parameters/Limit'
      responses:
        '200':
          description: Submissions loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicSubmissionListResponse'
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
  /api/v2/public/accounts/{accountId}/campaigns/{campaignId}/exports:
    post:
      tags: [PublicSubmissions]
      operationId: v2ExportCampaignResults
      summary: Generate a campaign answer export inline.
      description: |
        Builds the same answer-matrix workbook the in-app campaign export
        produces, and returns it INLINE in the JSON body - xlsx as base64,
        csv and json as a string. There is no external storage and no signed
        URL, so large campaigns produce large responses.

        Add download=1 and the same file is STREAMED instead of embedded, with
        Content-Disposition and no Content-Length on the chunked csv/json arms.
        Both arms are serialised from one model, so the bytes are identical; the
        envelope is what carries rowCounts, population, the codebook, the shape
        report and the notes.

        The export always contains real answers; the submissions:read:answers
        scope does not gate THOSE. It does gate the auditor's review data - see
        REVIEW below. Every call writes a CAMPAIGN audit-log entry with
        via=v2_public_api. Scope results:export.

        REVIEW: the ans: cells always hold the auditor-MERGED value, the same
        substitution the scoring engine makes. A token holding
        submissions:read:answers additionally receives
        ans:<question>::original (present only where the merge changed the
        value), the rev:<question>::* columns, the per-submission review counts
        and the notes section; a token without it receives none of those and
        export.reviewsIncluded is false. Asking for them explicitly with
        filters.includeReviews: true and no scope is refused with 403 and code
        REVIEW_SCOPE_REQUIRED rather than downgraded silently.

        The json arm carries a raw answers object beside each exploded row, and
        it redacts on the SAME terms as the columns. With
        submissions:read:answers it is the respondent's bag as stored, before
        the auditor merge - the lossless record, disclosing no more than the
        ans:<question>::original columns beside it. Without the scope it is the
        MERGED bag, identical to the ans: cells, so the pre-correction values
        cannot be recovered by diffing the two. The codebook entry for the
        answers key states which of the two the file holds.

        PROVENANCE: syntheticRunId, syntheticGenerator and syntheticSeed are on
        every row, blank for a real submission, so a downloaded file can be
        reconciled against a purge by run.

        POPULATION: completed and reopened submissions only. In-progress drafts
        are excluded unless filters.includeDrafts is true, and export.population
        states which population the file holds. Since v2 1.1.0 the
        submissions LIST endpoint above defaults to the SAME population, so an
        unfiltered listing's meta.total and this file's rowCounts.submissions
        agree for a campaign nobody filtered.

        CODEBOOK: export.codebook documents EVERY generated column - the fixed
        ones and the ans: ones - with the question title in the default locale,
        the element type, and the row/column/item label a part came from, plus
        one kind=json entry for the json arm's answers key. It is the Codebook
        sheet in the xlsx arm and a field in all three arms, so a csv consumer
        is not left decoding headers. export.shapeReport is the
        per-question census of measured answer shapes; a value whose shape does
        not fit its question's column plan is emitted verbatim in a
        <question>::raw column and counted there rather than reshaped.

        SETS AND SCORES (SS-ADM batch 2): the xlsx arm adds one sheet per
        Specialized Set after the six, named by the set label's abbreviation
        (or its name). A question belongs to a set through its own
        specializedSet:<label> chip, or through its assessment when the
        assessment row or its campaign-graph node carries one Specialized set
        label. A set sheet holds one row per response that answered at least
        one of the set's questions: submissionId, assessmentId, assessmentKey,
        unitKey, personKey, organisation and status, then the set's columns
        exactly as the Submissions sheet has them. When an assessment carries
        every question a platform score definition reads, score:<code>::<field>
        columns follow the answer columns on Submissions and on the set's
        sheet, computed from the auditor-merged answers (SS-ADM's are placed,
        processScore, capacityScore, cell, states, composite, band, toComplete,
        responseCell, outcomeCheck1 to outcomeCheck4 and definitionVersion). The codebook gains a sheet field and a score
        kind, and the json arm gains a sets array (sheet, labelId, name, chip,
        assessmentIds, columns, submissionIds) whose rows are the submissions
        array's, joined by submissionId. The csv arm is still the Submissions
        sheet alone. Every existing column keeps its name and place.

        CSV FILES (SS-ADM batch 2): csvSheets all, with format csv and
        download=1, answers a zip (application/zip, campaign_<id>_report.zip,
        with a Content-Length) holding one csv per sheet in book order, the
        set sheets included. Each file is named after its sheet in lower case
        (summary.csv, submissions.csv, codebook.csv, ss-adm.csv), with any
        character a Windows file name cannot hold replaced by _, and begins
        with a UTF-8 byte order mark so a spreadsheet reads accented text
        correctly; the plain csv arm stays without one. csvSheets all without
        download=1, or with another format, is refused with 400 rather than
        answered with the one csv.
      parameters:
        - $ref: '../components/v2-common.yaml#/components/parameters/AccountId'
        - $ref: '../components/v2-common.yaml#/components/parameters/CampaignId'
        - name: download
          in: query
          required: false
          description: |
            Pass 1 or true to receive the FILE (streamed, with
            Content-Disposition) instead of the JSON envelope. Anything else -
            including an absent parameter - keeps the envelope, so no existing
            integration changes behaviour.
          schema:
            type: string
            enum: ['1', 'true']
      requestBody:
        required: false
        description: An absent or unparseable body is treated as an empty object, which exports everything as xlsx.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportResultsRequest'
      responses:
        '200':
          description: |
            Export generated. Without download=1 the file arrives inline in the
            JSON envelope; with it, the response IS the file.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportResultsResponse'
            text/csv:
              schema: { type: string, description: download=1 with format csv. }
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet:
              schema: { type: string, format: binary, description: download=1 with format xlsx. }
            application/zip:
              schema: { type: string, format: binary, description: download=1 with format csv and csvSheets all. }
          headers:
            Content-Disposition:
              description: download=1 only - attachment; filename="campaign_<id>_report.<ext>".
              schema: { type: string }
        '400': { $ref: '../../v1/components/errors.yaml#/components/responses/BadRequest' }
        '401': { $ref: '../../v1/components/errors.yaml#/components/responses/Unauthorized' }
        '403': { $ref: '../../v1/components/errors.yaml#/components/responses/Forbidden' }
        '404': { $ref: '../../v1/components/errors.yaml#/components/responses/NotFound' }
        '429': { $ref: '../../v1/components/errors.yaml#/components/responses/TooManyRequests' }
        '500': { $ref: '../../v1/components/errors.yaml#/components/responses/InternalError' }
components:
  securitySchemes:
    serviceToken:
      $ref: '../components/v2-security.yaml#/components/securitySchemes/serviceToken'
  schemas:
    SubmissionStatus:
      type: string
      description: |
        completed is a normal submit; in_progress is a saved draft; reopened is
        a submission an auditor or admin sent back for correction.
      enum: [in_progress, completed, reopened]
    ParticipantStatus:
      type: string
      enum: [Invited, Active, Suspended, Completed]
    ExportFormat:
      type: string
      description: Defaults to xlsx when the format property is absent or empty. Any other value is rejected with 400.
      enum: [xlsx, csv, json]
    PublicSubmission:
      type: object
      description: |
        Whitelisted submission projection (toPublicSubmission). accountId,
        startedAt, createdAt, reopenedAt, and reopenedBy are internal and
        excluded. answers is present only for a token holding
        submissions:read:answers.
      required: [id, assessmentId, campaignId, status, submittedAt]
      properties:
        id:
          type: string
        assessmentId:
          type: string
        campaignId:
          type: string
        participantId:
          type: string
          description: Absent for an anonymous or unclaimed submission.
        unitKey:
          type: string
          description: |
            The unit instance this submission belongs to (since 1.2.0):
            participant:<participantId>, organisation:<organisationId> or
            group:<labelGroupId>:<labelKey>. One completed submission exists
            per (assessment, unit instance), so this is the key to group by
            when the respondent is not the unit of analysis. Absent on a
            walk-up's row, on a row filed before the column existed, and on a
            row whose respondent the unit could not place.
        submittedEmail:
          type: string
          format: email
        status:
          $ref: '#/components/schemas/SubmissionStatus'
        submittedAt:
          type: integer
          description: Epoch milliseconds.
        answers:
          description: The raw answer blob, keyed by question. Shape follows the assessment's template, so it is not fixed.
    ExportResultsFilters:
      type: object
      description: Validated by normalizeCampaignReportFilters. An invalid participantStatus, or submittedFrom greater than submittedTo, is rejected with 400.
      properties:
        assessmentId:
          type: string
        participantStatus:
          $ref: '#/components/schemas/ParticipantStatus'
        submittedFrom:
          type: integer
          description: Epoch milliseconds, inclusive.
        submittedTo:
          type: integer
          description: Epoch milliseconds, inclusive.
        includeDrafts:
          type: boolean
          description: |
            Include in-progress drafts. Defaults to false. Strictly boolean - a
            string such as "false" is rejected with 400, because it is truthy
            and coercing it would silently ship half-typed autosaves as data.
        includeReviews:
          type: boolean
          description: |
            Assert that the file must carry the auditor's review data. Optional:
            a token holding submissions:read:answers receives it either way.
            Passing true WITHOUT that scope is refused with 403 and code
            REVIEW_SCOPE_REQUIRED - the point of the flag is to turn a silent
            downgrade into an error an integrator can act on. Strictly boolean.
    ExportResultsRequest:
      type: object
      properties:
        format:
          $ref: '#/components/schemas/ExportFormat'
        filters:
          $ref: '#/components/schemas/ExportResultsFilters'
        csvSheets:
          type: string
          enum: [submissions, all]
          default: submissions
          description: |
            Which sheets a csv download holds. submissions, the default, is the
            Submissions sheet alone, as the csv arm has always answered. all is
            a zip of one csv per sheet and needs format csv and download=1;
            anything else is refused with 400.
    ExportFile:
      type: object
      description: |
        The generated file. For xlsx the bytes arrive as workbookBase64 with
        sheetNames; for csv and json the text arrives as content with a
        contentType. Exactly one of those pairs is populated per format.
      required: [format, fileName, rowCounts]
      properties:
        format:
          $ref: '#/components/schemas/ExportFormat'
        fileName:
          type: string
        workbookBase64:
          type: string
          description: xlsx only. Base64-encoded workbook bytes.
        sheetNames:
          type: array
          description: xlsx only.
          items:
            type: string
        content:
          type: string
          description: csv and json only. The file text.
        contentType:
          type: string
          description: The file's media type, on every arm.
        reviewsIncluded:
          type: boolean
          description: |
            Whether this file carries the auditor's review data. False means the
            token lacked submissions:read:answers - NOT that nothing was
            reviewed. An integrator diffing nightly pulls needs to tell those
            apart.
        notes:
          type: array
          description: |
            The auditor notes the file carries; empty when reviewsIncluded is
            false. A review whose includeInExport is unticked never appears
            here - the reviewNotesWithheldCount column on the submission rows
            reports the withholding.
          items:
            $ref: '#/components/schemas/ExportNoteRow'
        rowCounts:
          type: object
          required: [participants, submissions, draftsExcluded]
          properties:
            participants:
              type: integer
            submissions:
              type: integer
            draftsExcluded:
              type: integer
              description: In-progress drafts left out; 0 when includeDrafts is true.
        population:
          $ref: '#/components/schemas/ExportPopulation'
        codebook:
          type: array
          items:
            $ref: '#/components/schemas/ExportCodebookEntry'
        shapeReport:
          type: array
          items:
            $ref: '#/components/schemas/ExportShapeReportRow'
    ExportNoteRow:
      type: object
      description: |
        One auditor note. The author is an identity-folded key built from the
        reviewer's principal id; a reviewer's address is never exported.
      required: [submissionId, questionKey, note, authorKey]
      properties:
        submissionId:
          type: string
        questionKey:
          type: string
        questionTitle:
          type: string
        note:
          type: string
        hashtags:
          type: string
          description: The review's hashtags, joined with |.
        authorKey:
          type: string
          description: person:<id> or user:<id> - never an email address.
        reviewedAtIso:
          type: string
    ExportPopulation:
      type: object
      description: Which rows the file holds, so a workbook read months later is self-describing.
      required: [includeDrafts, submissions, draftsExcluded]
      properties:
        includeDrafts:
          type: boolean
        submissions:
          type: integer
        draftsExcluded:
          type: integer
    ExportCodebookEntry:
      type: object
      description: |
        One generated column, described. Present for every column of the
        Submissions sheet - the fixed ones and the generated ans: ones.

        The fixed columns are submissionId, assessmentId, assessmentKey,
        assessmentName, assessmentUnit, assessmentDefaultAvailability,
        templateId, templateVersion, templateFingerprint,
        participantId, unitKey, personKey, participantEmail, organisation,
        participantClass, participantRole, participantStatus, labelsCsv, one
        label:<key> per key:value label prefix, one meta:<path> per participant
        metadata path, then status, startedAtIso, submittedAtIso,
        completedAtIso, campaignClosedAtIso, answerKeyCount, syntheticRunId,
        syntheticGenerator, syntheticSeed, and the review counts (reviewCount,
        reviewVerifiedCount, reviewModifiedCount, reviewLockedCount,
        reviewNotesExportedCount, reviewNotesWithheldCount,
        reviewLastReviewedAtIso).

        The answer columns are named ans:<question>, ans:<question>::<part> or
        ans:<question>::<part>::<sub>, and hold the auditor-MERGED value.
        ans:<question>::original carries the respondent's own value where the
        merge changed it, and rev:<question>::status / ::modifiedApplied /
        ::locked / ::reviewedAtIso / ::reviewerKey describe the review - all
        four only when the token may see review data.
      required: [column, kind, description]
      properties:
        column:
          type: string
        questionKey:
          type: string
        questionTitle:
          type: string
          description: The question title in the default locale, when a template supplied one.
        questionType:
          type: string
        kind:
          type: string
          description: |
            fixed is a non-answer column. value is a scalar answer. cell is one
            matrix row or multipletext item; gridCell is one matrixdropdown
            row x column. choice is a 0/1 indicator for one checkbox or tagbox
            choice. rank is one ranking choice: its 1-based position in the
            respondent's order, blank when it was not ranked. file holds
            uploaded file names, never content. raw holds answers whose stored
            shape did not fit the column plan, verbatim. json is the json arm's
            answers key and note a codebook-only note (csv, population). score is
            a computed score:<code>::<field> column; part names its field.
          enum: [fixed, value, cell, gridCell, choice, rank, file, raw, json, note, score]
        part:
          type: string
        partLabel:
          type: string
        subPart:
          type: string
        subPartLabel:
          type: string
        assessmentId:
          type: string
        description:
          type: string
        sheet:
          type: string
          description: |
            Campaign export only: every sheet the column appears on, joined
            with | (Submissions, and a Specialized Set's sheet for that set's
            columns). Empty for a key that is on no sheet, such as the json
            arm's answers.
    ExportShapeReportRow:
      type: object
      description: |
        The per-question census of MEASURED answer shapes, and what was done
        with them. mappedCount + rawCount always equals answeredCount.
      required: [questionKey, plannedShape, columnCount, answeredCount, mappedCount, rawCount, shapes]
      properties:
        questionKey:
          type: string
        questionTitle:
          type: string
        questionType:
          type: string
        plannedShape:
          type: string
          enum: [empty, scalar, list, cells, grid, files, raw]
        columnCount:
          type: integer
        answeredCount:
          type: integer
        mappedCount:
          type: integer
        rawCount:
          type: integer
        shapes:
          type: string
          description: The census, e.g. "scalar=14137|cells=230".
    PublicSubmissionListResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data, meta]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/PublicSubmission'
            meta:
              allOf:
                - $ref: '../components/v2-common.yaml#/components/schemas/PageMeta'
                - type: object
                  required: [answersIncluded, draftsExcluded]
                  properties:
                    answersIncluded:
                      type: boolean
                      description: Whether this caller's scopes allowed answer content in the payload.
                    draftsExcluded:
                      type: integer
                      description: |
                        Added in 1.1.0. How many in-progress drafts the default
                        population rule removed from THIS listing, counted after
                        the other filters and before paging. 0 when ?status= or
                        includeDrafts=1 named the population - which is not the
                        same as "there are no drafts", so read it beside
                        meta.total rather than on its own.
    ExportResultsResponse:
      allOf:
        - $ref: '../../v1/components/envelopes.yaml#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: object
              required: [campaignId, format, filters, generatedAt, export]
              properties:
                campaignId:
                  type: string
                format:
                  $ref: '#/components/schemas/ExportFormat'
                filters:
                  $ref: '#/components/schemas/ExportResultsFilters'
                generatedAt:
                  type: integer
                  description: Epoch milliseconds.
                export:
                  $ref: '#/components/schemas/ExportFile'
