Unqork Revisions API

openapi: 3.2.0
info:
  version: 1.0.0
  x-logo:
    url: https://developers.unqork.io/unqork-logo.png
    backgroundColor: '#FFFFFF'
  title: Unqork Customer Revisions API
  description: Unqork's customer REST API, based on open standards, allows you to set and retrieve module submission data, as well as control other aspects of your Unqork environment.
servers:
- url: https://{host}/api/1.0
  variables:
    host:
      default: env.unqork.io
      description: Environment host
security:
- OAuth2: []
tags:
- name: Revisions
paths:
  /modules/{moduleId}/submissions/{submissionId}/revisions:
    get:
      x-unqork-service: true
      tags:
      - Revisions
      summary: Get Module Submission Revisions
      operationId: getModuleSubmissionRevisions
      description: 'Get all revisions for a submission. The data field is left empty.

        ### Authorization Required:

        - See Submission Access (Submission Access)'
      parameters:
      - $ref: '#/components/parameters/ModuleID'
      - name: submissionId
        in: path
        description: ID of module submission to retrieve revisions for
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/SubmissionSortBy'
      - $ref: '#/components/parameters/SubmissionSortOrder'
      - $ref: '#/components/parameters/MetadataFilterString'
      responses:
        '200':
          description: Revisions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RetrievedRevisionsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /modules/{moduleId}/submissions/{submissionId}/revisions/{revisionId}:
    get:
      x-unqork-service: true
      tags:
      - Revisions
      summary: Get Module Submission Revision
      operationId: getModuleSubmissionRevision
      description: 'Gets a single revision for a submission. Revision data is transformed and returned in a specific format, based on the specified transform. JSON revisions data is returned as an object, XML data is returned as a string, and PDF data is returned as a Cloud Storage Delivery URL to the rendered PDF (and optionally base 64 data).

        ### Authorization Required:

        - See Submission Access (Submission Access)'
      parameters:
      - $ref: '#/components/parameters/ModuleID'
      - name: submissionId
        in: path
        description: ID of module submission to retrieve revisions for
        required: true
        schema:
          type: string
      - name: revisionId
        in: path
        description: ID of the particular submission revision to retrieve. To retrieve all submission revisions, do not include this path parameter
        required: true
        schema:
          type: string
      - name: transformName
        in: query
        description: Transform to apply to module for output. Transform must be configured and designated for output. Available transforms may be listed via the /transforms endpoint. Only available for single revisions
        schema:
          type: string
      - name: includeRaw
        in: query
        description: Whether to include the untransformed raw submission data in addition to the transformed data. Raw submission data may contain [Cloud Storage Delivery URLs](#section/Cloud-Storage-Delivery). Only available for single revisions
        schema:
          type: boolean
      - name: includeBase64
        in: query
        description: Whether to include base64 PDF data in addition to the PDF url (for "njk-pdf" transforms). Only available for single revisions
        schema:
          type: boolean
      - name: resolveCloudStorageUrls
        in: query
        description: When `transformName` is specified, Cloud Storage URLs are already resolved to the original base64 value. When this flag is specified, resolve Cloud Storage URLs to base64 data inside "rawData", as well. Only available for single revisions
        schema:
          type: boolean
      - $ref: '#/components/parameters/DataFields'
      responses:
        '200':
          description: Revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedRevisionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}/submissions/{submissionId}/revisions:
    get:
      x-unqork-service: true
      tags:
      - Revisions
      summary: Get Workflow Submission Revisions
      operationId: getWorkflowSubmissionRevisions
      description: 'Gets all revisions for a submission. The data field is left empty.

        ### Authorization Required:

        - See Submission Access (Submission Access)'
      parameters:
      - $ref: '#/components/parameters/WorkflowID'
      - name: submissionId
        in: path
        description: ID of workflow submission to retrieve revisions for
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/SubmissionSortBy'
      - $ref: '#/components/parameters/SubmissionSortOrder'
      - $ref: '#/components/parameters/MetadataFilterString'
      responses:
        '200':
          description: Revisions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RetrievedRevisionsResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /workflows/{workflowId}/submissions/{submissionId}/revisions/{revisionId}:
    get:
      x-unqork-service: true
      tags:
      - Revisions
      summary: Get Workflow Submission Revision
      operationId: getWorkflowSubmissionRevision
      description: 'Gets a single revision for a submission. Revision data is transformed and returned is a specific format, based on the specified transform. JSON revisions data is returned as an object, XML data is returned as a string, and PDF data is returned as a Cloud Storage Delivery URL to the rendered PDF (and optionally base 64 data).

        ### Authorization Required:

        - See Submission Access (Submission Access)'
      parameters:
      - $ref: '#/components/parameters/WorkflowID'
      - name: submissionId
        in: path
        description: ID of workflow submission to retrieve revisions for
        required: true
        schema:
          type: string
      - name: revisionId
        in: path
        description: ID of the particular submission revision to retrieve. To retrieve all submission revisions, do not include this path parameter
        required: true
        schema:
          type: string
      - name: transformName
        in: query
        description: Transform to apply to workflow for output. Transform must be configured and designated for output. Available transforms may be listed via the /transforms endpoint. Only available for single revisions
        schema:
          type: string
      - name: includeRaw
        in: query
        description: Whether to include the untransformed raw submission data in addition to the transformed data. Raw submission data may contain [Cloud Storage Delivery URLs](#section/Cloud-Storage-Delivery). Only available for single revisions
        schema:
          type: boolean
      - name: includeBase64
        in: query
        description: Whether to include base64 PDF data in addition to the PDF url (for "njk-pdf" transforms). Only available for single revisions
        schema:
          type: boolean
      - name: resolveCloudStorageUrls
        in: query
        description: When `transformName` is specified, Cloud Storage URLs are already resolved to the original base64 value. When this flag is specified, resolve Cloud Storage URLs to base64 data inside "rawData", as well. Only available for single revisions
        schema:
          type: boolean
      - $ref: '#/components/parameters/DataFields'
      responses:
        '200':
          description: Revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievedRevisionResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    Offset:
      name: offset
      in: query
      description: Number of results to skip before selecting results. Offset is zero based.
      required: false
      schema:
        type: integer
        format: int32
        default: 0
    SubmissionSortBy:
      name: sortBy
      in: query
      description: Field to sort by (currently supported - `"created"`, `"modified"`)
      required: false
      schema:
        type: string
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return (default 50, maximum 50)
      required: false
      schema:
        type: integer
        format: int32
        default: 50
        maximum: 50
    WorkflowID:
      name: workflowId
      in: path
      description: Unique workflow ID
      required: true
      schema:
        type: string
    MetadataFilterString:
      name: metadataFilter
      in: query
      description: "Filter condition against submission \"metadata\" field. Value must be a stringified MongoDB query condition (see Examples, below). MongoDB [dot notation](https://docs.mongodb.com/manual/core/document/#dot-notation) is supported for keys.\n\nNOTE: MongoDB selectors that can be nested inside queries (such as [Comparison](https://docs.mongodb.com/manual/reference/operator/query/#comparison) and [Element](https://docs.mongodb.com/manual/reference/operator/query/#element) Selectors, e.g. `$eq`, `$in`, `$exists`) are supported. The following [Logical](https://docs.mongodb.com/manual/reference/operator/query/#logical) Selectors are also supported: `$and`, `$or`, `$nor`\n\nExamples:\n- `metadataFilter: {\"checkpoints.complete\": 1234}`\n- `metadataFilter: {\"checkpoints.complete\": {\"$exists\": true}, \"checkpoints.processed\": {\"$exists\": false}}`\n\n  - Will return submissions where both `metadata.checkpoints.complete` exists AND `metadata.checkpoints.processed` does not exist\n"
      schema:
        type: string
    DataFields:
      name: dataFields
      in: query
      description: 'Comma-separated list of dot-notation `data` fields to retrieve; for example, `&dataFields=field1,also.field2` will retrieve `{"data":{"field1":"v1","also":{"field2":"v2"}}}`. Do not include "data" in front of each field. All other submission fields will always be retrieved.

        '
      schema:
        type: string
    SubmissionSortOrder:
      name: sortOrder
      in: query
      description: Order of sort, if `sortBy` is specified.  One of [`1` (ascending),`-1` (descending)]
      required: false
      schema:
        type: integer
        enum:
        - 1
        - -1
        default: 1
    ModuleID:
      name: moduleId
      in: path
      description: Unique module ID
      required: true
      schema:
        type: string
  schemas:
    ValidationErrors:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          path:
            type: string
          label:
            type: string
          parent:
            type: string
          message:
            type: string
    Error:
      type: object
      description: Error
      required:
      - code
      - message
      properties:
        code:
          description: HTTP status code
          type: integer
          format: int32
          enum:
          - 400
          - 401
          - 403
          - 404
          - 412
          - 500
        message:
          description: Error message
          type: string
    RetrievedRevisionResponse:
      type: object
      required:
      - id
      - submission
      properties:
        id:
          type: string
          description: Revision id
        created:
          type: string
          description: Date of when the submission was created or modified (might be missing in old submissions)
        createdBy:
          type: string
          description: Creator or modifier of the submission (might be missing in old submissions)
        persistedInWormStorage:
          type: boolean
          description: whether the revision is WORM (Write-Once-Read-Many) compliant. [Click here](https://www.17a-4.com/regulations-summary/) for more information
        submission:
          type: object
          description: Submission object
          properties:
            id:
              type: string
            userId:
              type: string
              description: Submission owner
            formId:
              type: string
            created:
              type: string
              format: date-time
            modified:
              type: string
              format: date-time
            deleted:
              type: string
              format: date-time
            metadata:
              type: object
            formArchive:
              type: string
              description: The form version the revision was saved under
            data:
              type: object
              description: Transformed output data. Empty for calls that return multiple revisions
              properties:
                format:
                  type: string
                  enum:
                  - json
                  - xml
                  - pdf
                jsonData:
                  type: object
                xmlData:
                  type: string
                pdfUrl:
                  type: string
                  format: url
                pdfData:
                  type: string
                rawData:
                  type: object
        validationErrors:
          $ref: '#/components/schemas/ValidationErrors'
    RetrievedRevisionsResponse:
      type: object
      required:
      - id
      - submission
      properties:
        id:
          type: string
          description: Revision id
        created:
          type: string
          description: Date of when the submission was created or modified (might be missing in old submissions)
        createdBy:
          type: string
          description: Creator or modifier of the submission (might be missing in old submissions)
        persistedInWormStorage:
          type: boolean
          description: whether the revision is WORM (Write-Once-Read-Many) compliant. [Click here](https://www.17a-4.com/regulations-summary/) for more information
        submission:
          type: object
          description: Submission object
          properties:
            id:
              type: string
            userId:
              type: string
              description: Submission owner
            formId:
              type: string
            created:
              type: string
              format: date-time
            modified:
              type: string
              format: date-time
            deleted:
              type: string
              format: date-time
            metadata:
              type: object
            formArchive:
              type: string
              description: The form version the revision was saved under
        validationErrors:
          $ref: '#/components/schemas/ValidationErrors'
  securitySchemes:
    OAuth2:
      description: "The Unqork API implements the [OAuth 2.0 Client Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) and the [OAuth 2.0 Password Grant](https://tools.ietf.org/html/rfc6749#section-1.3.3). Access via OAuth2 Client Credentials Grant can be utilized by creating Client Credentials through the API Access Management Administration page. Access via OAuth2 Password Grant can be enabled for all users in Environment Administration. Once OAuth2 Password Grant is enabled, all Unqork users can use their Unqork username/password to retrieve an access token.\n\nIn order to utilize any of the API resources, you must first retrieve an access token by POSTing your credentials to the access token URL, e.g. using `curl`:\n```\n  $ curl -u '{clientId}:{clientSecret}' -X POST --basic https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=client_credentials\"\n```\nOr:\n```\n  $ curl -X POST https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token -d \"grant_type=password&username={username}&password={password}\"\n```\nThis returns an \"access_token\", which you would then retain and use in any subsequent resource requests. **Access tokens expire after one hour, at which point you must retrieve a new one.** The access token should be included in a request header:\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/api/1.0/{endpoint}\n```\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A
        password:
          tokenUrl: https://xyzfinancial.unqork.io/api/1.0/oauth2/access_token
          scopes:
            none: N/A
x-provenance:
  method: harvested
  publisher: Unqork
  source: https://developers.unqork.io/api/1.0/openapi.yml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)