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: "\nUnqork'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. You can use any web development language to access the API, as communication is over secured HTTP.\n## URI Structure and Methods\nAll API communication will occur over SSL (HTTPS). All API responses are in JSON format.\nAll Unqork requests begin with the prefix:\n\n```\n  https://{yourSubdomain}.unqork.io/api/1.0\n```\n\nFor example, if your subdomain is **xyzfinancial**, you would use the prefix `https://xyzfinancial.unqork.io/api/1.0`.\n\nThe next segment of the URI path will vary based on the endpoint of the request.\n\nA given endpoint (resource) has a series of actions (methods) associated with it. The Unqork API supports these standard HTTP methods:\n\n- **GET** - retrieves data\n\n- **PUT** - updates existing data\n\n- **POST** - creates new data\n\n- **DELETE** - deletes existing data\n\nFor example, you can use the POST action on the module submission resource to create a new module submission.\n## Paging\nPaged endpoints use the [Link header](https://www.w3.org/wiki/LinkHeader). If the link header \"next\" is present, then there are more items to retrieve, and the \"next\" should be followed.\n## Cloud Storage Delivery\nUnqork exposes generated PDFs, uploaded attachments, and other file-like pieces of submission data via Cloud Storage Delivery URLs. These are signed, expiring links that allow the user to securely retrieve files stored in Unqork. Links can appear inside raw submission data, or they can be returned from PDF transform submission endpoints.\n\nThese links cannot be shared with other parties; only the user who generates the unique link (by either submitting the file or accessing the submission where the file has been saved) will be able to use that specifically generated link. This means that the user must be authenticated (either in the browser, or by passing a valid OAuth Bearer token) in order to retrieve the file.\n\nCloud Storage Delivery URLs will look like this:\n\n`https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}`\n\nThe file can be retrieved by accessing the link in the browser, or like this:\n\n```\n  $ curl -H \"Authorization: Bearer {access_token}\" https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}\n```\n## Nomenclature\nPreviously, \"Modules\" were called \"Forms\". This nomenclature change affects all endpoints documented here in paths, request parameters, and response bodies (e.g. `forms -> modules`, `formId -> moduleId`; however, the behaviors of the endpoints are the same. The previous endpoints will continue to be supported, but they will be deprecated in the future.\n## API Access Notes\n#### Express Module and Workflow Access <a name=\"express-module-workflow-access\"></a>\nExpress Module and Workflow Access is determined by a User's Role and the Module's permissions. An Express User's Role is specified at the environment level, but can be overwritten at the Application level using Application Roles. If Module Permissions are used, the permission settings will specify what access (Read, Write, Obfuscate, or None) a User will have to the Module. Anonymous Users may also be able to access a Module if the permission settings allow it.\n#### Submission Access <a name=\"submission-access\"></a>\nSubmission Access is determined by a User's Role, Groups, and if they are the owner of the Submission. A Submission owner is the user that created or updated the Submission. If a user is a Submission owner, Designer Administrator, or an Express Super User, the user has access to the Submission. If the User does not have access to the Module or Workflow that the Submission is associated with, then the User will not have access to the Submission. See Express Module and Workflow Access ([Express Module and Workflow Access](#express-module-workflow-access)). A User's Role Groups can also provide a User Access to a Submission. A User needs to have Intersecting Groups with the Submission Owner. Intersecting Groups means a User has a Role with a Group (Groups assigned directly to the User do not count) that is in the Submission owner's groups (the Submission owners Role Groups or the Submission owners User Groups). If a User has Intersecting Groups:\n- And the Group type is ignore role, a User that has Intersecting Groups can access the Submission.\n- And the Group type is Role descendents, a User that has Intersecting Groups and the Submission owner's Role is a descendant of the User's Role then the User can access the Submission.\n- And the Group type is own Role and descendents, a User that has Intersecting Groups and the Submission owner's Role is a descendent of the User's Role or the User's Role is the same as the Submission owner's Role then the User can access the Submission.\n"
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.\n### Authorization Required:\n  - See Submission Access ([Submission Access](#submission-access))\n"
      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](#section/Cloud-Storage-Delivery) to the rendered PDF (and optionally base 64 data).\n### Authorization Required:\n  - See Submission Access ([Submission Access](#submission-access))\n"
      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.\n### Authorization Required:\n  - See Submission Access ([Submission Access](#submission-access))\n"
      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](#section/Cloud-Storage-Delivery) to the rendered PDF (and optionally base 64 data).\n### Authorization Required:\n  - See Submission Access ([Submission Access](#submission-access))\n"
      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:
  schemas:
    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'
    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
  parameters:
    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
    SubmissionSortBy:
      name: sortBy
      in: query
      description: Field to sort by (currently supported - `"created"`, `"modified"`)
      required: false
      schema:
        type: string
    ModuleID:
      name: moduleId
      in: path
      description: Unique module ID
      required: true
      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
    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
    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
    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
    WorkflowID:
      name: workflowId
      in: path
      description: Unique workflow ID
      required: true
      schema:
        type: string
  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