Unqork Modules 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 Modules 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: Modules
paths:
  /modules:
    get:
      tags:
      - Modules
      summary: Get Modules
      operationId: getModules
      description: "Returns module objects. This is a paged endpoint (see Paging).\n### Authorization Required:\n  - Application View\n"
      parameters:
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: Modules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ModuleResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /modules/{moduleId}:
    get:
      tags:
      - Modules
      summary: Get Module
      operationId: getModule
      description: "Returns a module object based on a module ID.\n### Authorization Required:\n  - Application View\n"
      parameters:
      - name: moduleId
        in: path
        description: ID of module to retrieve
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Module
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /modules/{moduleId}/restore:
    post:
      tags:
      - Modules
      summary: Restore a Deleted Module
      operationId: restoreDeletedModule
      description: "Restores a soft-deleted module.\n### Authorization Required:\n  - Application Create\n"
      parameters:
      - name: moduleId
        in: path
        description: ID of module to restore
        required: true
        schema:
          type: string
      requestBody:
        description: 'NOTE: Any of the options below will override existing relationships the module had at the time of deletion.

          '
        content:
          application/json:
            schema:
              type: object
              properties:
                shareToEnvironment:
                  description: 'Whether to share the module to the environment


                    NOTE: If specified, request cannot include `workspaceId` or `applicationId`.

                    '
                  type: boolean
                workspaceId:
                  description: "Workspace ID module will be shared with\n\n\nExamples\n\n  Restore and share to workspace ID: `6053e968afcc293120198785`\n\n  Request\n\n  ```\n   {\n     \"workspaceId\": \"6053e968afcc293120198785\",\n   }\n  ```\n\n\nNOTE: If `applicationId` also specified, will connect the module to the application (the application must be part of the workspace)\n\nRestore and connect to application `6078e938d87660707f31c624` in workspace `6053e968afcc293120198785`\n\n Request\n\n ```\n  {\n    \"workspaceId\": \"6053e968afcc293120198785\",\n    \"applicationId\": \"6078e938d87660707f31c624\"\n  }\n ```\n"
                  type: string
                applicationId:
                  description: "Application ID to which the module will be restored (will not share the module)\n\nExample\n\n Request\n\n ```\n  {\n    \"applicationId\": \"6078e938d87660707f31c624\"\n  }\n ```\n"
                  type: string
      responses:
        '204':
          description: Successfully Restored
        '422':
          description: App/workspace relationship does not exist/or options specified are invalid
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /modules/{moduleId}/execute:
    put:
      x-unqork-service: true
      tags:
      - Modules
      summary: Execute Module
      operationId: executeModule
      description: "Execute module rules/validations configured in specified module with specified submission data, optionally save data. The response will include the saved submission data that would be available in the specified module.\n### Authorization Required:\n  - Designer Administrator or Express Read\n"
      parameters:
      - name: moduleId
        in: path
        description: ID of module to use to execute submission
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModuleExecuteRequest'
      responses:
        '200':
          description: Submission executed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        '412':
          description: Validation and/or execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        2XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        4XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        5XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /modules/{moduleId}/api:
    get:
      x-unqork-service: true
      tags:
      - Modules
      summary: Execute via Proxy - GET
      operationId: apiProxySSEGet
      description: "API request layer for Server Side Execute to allow HTTPS calls to Execute a Module. The path and query string are flexible.\n### Authorization Required:\n  - Designer Administrator or Express Read\n"
      parameters:
      - name: moduleId
        in: path
        description: "The module specified by moduleId must meet the following requirements -\n  - It MUST be marked as Server-side Execute Only\n  - It MAY be marked as anonymous\n  - It MAY reference a submission data getter for object key _request\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Submission validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        '412':
          description: Validation and/or execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        2XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        4XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        5XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      x-unqork-service: true
      tags:
      - Modules
      summary: Execute via Proxy - POST
      operationId: apiProxySSEPost
      description: "API request layer for Server Side Execute to allow HTTPS calls to Execute a Module. The request format is flexible and may include files, text, xml or JSON Object. The path and query string are also flexible.\n### Authorization Required:\n  - Designer Administrator or Express Read\n"
      parameters:
      - name: moduleId
        in: path
        description: "The module specified by moduleId must meet the following requirements -\n  - It MUST be marked as Server-side Execute Only\n  - It MAY be marked as anonymous\n  - It MAY reference a submission data getter for object key _request\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Submission validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        '412':
          description: Validation and/or execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        2XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        4XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        5XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      x-unqork-service: true
      tags:
      - Modules
      summary: Execute via Proxy - PUT
      operationId: apiProxySSEPut
      description: "API request layer for Server Side Execute to allow HTTPS calls to Execute a Module. The request format is flexible and may include files, text, xml or JSON Object. The path and query string are also flexible.\n### Authorization Required:\n  - Designer Administrator or Express Read\n"
      parameters:
      - name: moduleId
        in: path
        description: "The module specified by moduleId must meet the following requirements -\n  - It MUST be marked as Server-side Execute Only\n  - It MAY be marked as anonymous\n  - It MAY reference a submission data getter for object key _request\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Submission validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        '412':
          description: Validation and/or execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        2XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        4XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        5XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      x-unqork-service: true
      tags:
      - Modules
      summary: Execute via Proxy - PATCH
      operationId: apiProxySSEPatch
      description: "API request layer for Server Side Execute to allow HTTPS calls to Execute a Module. The request format is flexible and may include files, text, xml or JSON Object. The path and query string are also flexible.\n### Authorization Required:\n  - Designer Administrator or Express Read\n"
      parameters:
      - name: moduleId
        in: path
        description: "The module specified by moduleId must meet the following requirements -\n  - It MUST be marked as Server-side Execute Only\n  - It MAY be marked as anonymous\n  - It MAY reference a submission data getter for object key _request\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Submission validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        '412':
          description: Validation and/or execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        2XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        4XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        5XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      x-unqork-service: true
      tags:
      - Modules
      summary: Execute via Proxy - DELETE
      operationId: apiProxySSEDelete
      description: "API request layer for Server Side Execute to allow HTTPS calls to Execute a Module. The path and query string are flexible.\n### Authorization Required:\n  - Designer Administrator or Express Read\n"
      parameters:
      - name: moduleId
        in: path
        description: "The module specified by moduleId must meet the following requirements -\n  - It MUST be marked as Server-side Execute Only\n  - It MAY be marked as anonymous\n  - It MAY reference a submission data getter for object key _request\n"
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Submission validated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        '412':
          description: Validation and/or execution error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        2XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleExecuteResponse'
        4XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FailedExecuteResponse'
        5XX:
          description: Custom HTTP status code if set by server side execution for API modules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ExecutionError:
      type: object
      properties:
        type:
          type: string
        url:
          type: string
        component:
          type: string
        message:
          type: string
        code:
          type: integer
    ModuleExecuteResponse:
      type: object
      properties:
        id:
          type: string
        userId:
          type: string
          description: Submission owner
        moduleId:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
        deleted:
          type: string
          format: date-time
        data:
          type: object
          description: Raw output data
          properties:
            rawData:
              type: object
              description: Saved submission data
            resolved:
              type: object
              description: Submission data resulting from execution
        metadata:
          type: object
        validationErrors:
          $ref: '#/components/schemas/ValidationErrors'
        invalidNavigationPanels:
          $ref: '#/components/schemas/InvalidNavigationPanels'
    InvalidNavigationPanels:
      type: array
      items:
        type: object
        properties:
          key:
            type: string
          label:
            type: string
    ModuleExecuteRequest:
      type: object
      properties:
        submissionId:
          description: ID of module submission to use. If `submissionId` is unspecified and `save` is specified, a new submission will be created with `moduleId` as the module being executed and `userId` as the user making the request.
          type: string
        data:
          description: Raw data to include in submission data when executing (and saving, if specified).
          type: object
        metadata:
          $ref: '#/components/schemas/MetadataRequest'
        validate:
          description: Whether or not to validate submission data post-execution.
          type: boolean
          default: false
        save:
          description: Whether to save data for the existing submission (or create a new submission) after execution. Data will never be saved when an execution error is encountered.
          type: boolean
          default: false
        saveOnValidationError:
          description: If set to `true` (and both save and validate are also set to `true`), will save and send back a 2xx response, even if validation errors occurred.
          type: boolean
          default: false
        hydrateDataInitially:
          description: If set to `true`, will fully populate data object before module begins execution.
          type: boolean
          default: false
    MetadataRequest:
      type: object
      description: 'Object containing key-value pairs. To set nested values, this must be an object like `{"statuses.complete": "yes", "statuses.processed": "no"}`, which is MongoDB [dot notation](https://docs.mongodb.com/manual/core/document/#dot-notation).'
    ValidationErrors:
      type: array
      items:
        type: object
        properties:
          id:
            type: string
          path:
            type: string
          label:
            type: string
          parent:
            type: string
          message:
            type: string
    ModuleResponse:
      type: object
      required:
      - id
      - name
      - title
      - created
      - modified
      properties:
        id:
          type: string
        name:
          type: string
        title:
          type: string
        created:
          type: string
          format: date-time
        modified:
          type: string
          format: date-time
    FailedExecuteResponse:
      type: object
      properties:
        validationErrors:
          $ref: '#/components/schemas/ValidationErrors'
        invalidNavigationPanels:
          $ref: '#/components/schemas/InvalidNavigationPanels'
        executionError:
          $ref: '#/components/schemas/ExecutionError'
    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:
    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
  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