openapi: 3.0.3
info:
version: 1.0.0
x-logo:
url: 'https://developers.unqork.io/unqork-logo.png'
backgroundColor: '#FFFFFF'
title: Unqork Customer 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. You can use any web development language to access the API, as communication is over secured HTTP.
## URI Structure and Methods
All API communication will occur over SSL (HTTPS). All API responses are in JSON format.
All Unqork requests begin with the prefix:
```
https://{yourSubdomain}.unqork.io/api/1.0
```
For example, if your subdomain is **xyzfinancial**, you would use the prefix
`https://xyzfinancial.unqork.io/api/1.0`.
The next segment of the URI path will vary based on the endpoint of the request.
A given endpoint (resource) has a series of actions (methods) associated
with it. The Unqork API supports these standard HTTP methods:
- **GET** - retrieves data
- **PUT** - updates existing data
- **POST** - creates new data
- **DELETE** - deletes existing data
For example, you can use the POST action on the module submission
resource to create a new module submission.
## Paging
Paged 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.
## Cloud Storage Delivery
Unqork 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.
These 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.
Cloud Storage Delivery URLs will look like this:
`https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}`
The file can be retrieved by accessing the link in the browser, or like this:
```
$ curl -H "Authorization: Bearer {access_token}" https://xyzfinancial.unqork.io/fbu/files/{filePath}?signature={signature}
```
## Nomenclature
Previously, "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.
## API Access Notes
#### Express Module and Workflow Access <a name="express-module-workflow-access"></a>
Express 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.
#### Submission Access <a name="submission-access"></a>
Submission 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:
- And the Group type is ignore role, a User that has Intersecting Groups can access the Submission.
- 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.
- 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.
servers:
- url: https://{host}/api/1.0
variables:
host:
default: env.unqork.io
description: Environment host
security:
- OAuth2: []
paths:
/referstring:
post:
x-unqork-service: true
tags:
- Authentication
summary: Generates an encrypted referstring for authentication
operationId: generateReferString
description: >
This endpoint will generate encrypted refer strings that can be used to authenticate users into an Unqork environment
Environment Variables - The following Environment Variables are required
- key : key for encryption
- cipher : method of encryption. The default and recommended cipher is aes-256-gcm.
Include this refer string in the link to an Unqork resource as follows
```
<hostname>?refer=<referString>/#/display/<resource_id>
```
- hostname - host name of Unqork server
- referString - referString returned from API
- resource_id - Id of the Unqork resource to viewFor example, https://client.unqork.io?refer=<referString>/#/display/abcd123
Examples
Example 1: Generate Refer String for 1 day (default role)
Request
```
{
"userId": "user123",
"expireOffset": 1,
"expireMeasure": "days"
}
```
Response
```
{
"referString": "<encrypted refer string>"
}
```
Example 2: Generate Refer String for single use (recommended)
Request
```
{
"userId": "user123",
"expireOffset": 1,
"expireMeasure": "days",
"oneTimeUse": true
}
```
Response
```
{
"referString": "<encrypted refer string>"
}
```
Example 3: Generate Refer String for custom role
Request
```
{
"userId": "user123",
"expireOffset": 1,
"expireMeasure": "days",
"additionalParams": {
"role": "customRole"
}
}
```
Response
```
{
"referString": "<encrypted refer string>"
}
```
Example 4: Generate Refer String with custom user parameters
Request
```
{
"userId": "user123",
"expireOffset": 1,
"expireMeasure": "days",
"additionalParams": {
"custom1": "custom value 1",
"custom1": "custom value 2",
"custom1": "custom value 3"
}
}
```
Response
```
{
"referString": "<encrypted refer string>"
}
```
### Authorization Required:
- Designer Administrator
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ReferStringRequest'
responses:
'200':
description: Successful Generation
content:
application/json:
schema:
type: object
required:
- referString
properties:
referString:
description: The encrypted refer string containing user information
type: string
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/modules/{moduleId}/submissions':
get:
x-unqork-service: true
tags:
- Submissions
summary: Get Module Submissions
operationId: getModuleSubmissions
description: >
Returns module submission objects for a given module. This is a paged endpoint (see Paging). Module submission data is transformed and returned in a specific format, based on the specified transform. JSON submission 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).
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: transformName
in: query
description: Transform to apply to module for output. Transform must be configured and designated for for output. Available transforms may be listed via the /transforms endpoint
schema:
type: string
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Offset'
- $ref: '#/components/parameters/SubmissionSortBy'
- $ref: '#/components/parameters/SubmissionSortOrder'
- $ref: '#/components/parameters/IncludeDeleted'
- $ref: '#/components/parameters/MetadataFilterString'
- 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).
schema:
type: boolean
- name: includeBase64
in: query
description: Whether to include base64 PDF data in addition to the PDF url (for "njk-pdf" transforms)
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.
schema:
type: boolean
- $ref: '#/components/parameters/DataFields'
- name: filter
in: query
description: >
Filter conditions against submissions. Currently supported filter conditions are `userId`, `created`, and `modified`. The filters should be `;` separated, as shown below.
NOTE: When filtering on `created` and `modified`, all timestamps are in UTC.
Examples:
- `filter=userId=john@doe.com` will fetch all submissions owned by "john@doe.com"
- `filter=userId=john@doe.com;created>2019-06-11T21:50:57.067Z` will fetch all submissions owned by "john@doe.com" and created after "2019-06-11T21:50:57.067Z" (UTC)
- `filter=modified=2019-06-11T21:50:57.067Z` will fetch submissions modified at exactly "2019-06-11T21:50:57.067Z" (UTC)
- `filter=created>2019-06-11T00:00:00.000Z;created<2019-06-20T00:00:00.000Z` will fetch submissions created between "2019-06-11T00:00:00.000Z" (UTC) and "2019-06-20T00:00:00.000Z" (UTC)
Supported operators (as specified in this library [api-query-params](https://github.com/loris/api-query-params)):
- key=val `type=public`
- key>val `count>5`
- key>=val `rating>=9.5`
- key<val `createdAt<2016-01-01`
- key<=val `score<=-5`
- key!=val `status!=success`
- key=val1,val2 `country=GB,US`
- key!=val1,val2 `lang!=fr,en`
- key `phone`
- !key `!email`
- key=/value/<opts> `email=/@gmail\.com$/i`
- key!=/value/<opts> `phone!=/^06/`
Note: multiple forward slashes (/) are interpreted as a regex. To use a string comparison wrap your parameter with string(). Ex. email=string(/@gmail\.com$/i).
schema:
type: string
responses:
'200':
description: Submissions
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/RetrievedSubmissionResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
x-unqork-service: true
tags:
- Submissions
summary: Create Module Submission(s)
operationId: createModuleSubmissions
description: >
Creates one or more new module submission. Submission ID is auto-generated and returned. Module submission data must be provided as a JSON object. In case of multiple submissions, Request Body must contain an Array of below defined request body structure. Max Limit per request is 50.
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: transformName
in: query
description: Transform to apply to module for input. Transform must be configured and designated for for input. Available transform types may be listed via the /transforms endpoint.
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/NewSubmissionRequest'
responses:
'201':
description: Submission created
content:
application/json:
schema:
$ref: '#/components/schemas/SavedSubmissionResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
x-unqork-service: true
tags:
- Submissions
summary: Update Multiple Module Submissions
operationId: updateModuleSubmissions
description: >
Updates multiple module submissions. This operation supports partial "data" updates,
i.e. data that is sent in "data" may include some but not all of the submission data.
Partial metadata updates are supported without including the entire metadata object.
To increment a numeric data key (will also initialize), use "incrementData"
To delete a data key, use "unsetData".
To delete a metadata key, use "unsetMetadata".
To replace the entire data object, use the "replaceData" flag.
Module submission data must be provided as a JSON object.
Max Limit per request is 50.
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: replaceData
in: query
description: Whether to completely replace the submission data with the object passed in "data". This option is available to "Administrator" users only.
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSubmissionsRequest'
responses:
'200':
description: Submission updates
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatedSubmissionsResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
x-unqork-service: true
tags:
- Submissions
summary: Deletes Multiple Module Submissions
operationId: deleteModuleSubmissions
description: >
Deletes multiple module submission based on the ID supplied.
Note that module submissions are soft-deleted (marked deleted, but not removed).
Default Max Limit per request is 50
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: destroy
in: query
description: Whether to hard delete the submission from database. Value of 'destroy=true' will delete the submission. This option requires administrator privileges. Once deleted, the submission cannot be retrieved.
schema:
type: boolean
default: false
- name: ids
in: query
description: >
A comma seperated list of the ids required to be deleted.
Note - Max limit is 50 Per Request
Example - ?ids=id1,id2,id3....
schema:
type: string
responses:
'200':
description: Submission deleted
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatedSubmissionsResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/modules/{moduleId}/submissions/{submissionId}':
get:
x-unqork-service: true
tags:
- Submissions
summary: Get Module Submission
operationId: getModuleSubmission
description: >
Gets a single module submission. Module submission data is transformed and returned is a specific format, based on the specified transform. JSON submission 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).
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: submissionId
in: path
description: ID of module submission to retrieve
required: true
schema:
type: string
- name: transformName
in: query
description: Transform to apply to module for output. Transform must be configured and designated for for output. Available transforms may be listed via the /transforms endpoint
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).
schema:
type: boolean
- name: includeBase64
in: query
description: Whether to include base64 PDF data in addition to the PDF url (for "njk-pdf" transforms)
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.
schema:
type: boolean
- $ref: '#/components/parameters/DataFields'
responses:
'200':
description: Submission
content:
application/json:
schema:
$ref: '#/components/schemas/RetrievedSubmissionResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
x-unqork-service: true
tags:
- Submissions
summary: Update Module Submission
operationId: updateModuleSubmission
description: >
Updates a single module submission. This operation supports partial "data" updates,
i.e. data that is sent in "data" may include some but not all of the submission data.
Partial metadata updates are supported without including the entire metadata object.
To increment a numeric data key (will also initialize), use "incrementData"
To delete a data key, use "unsetData".
To delete a metadata key, use "unsetMetadata".
Module submission data must be provided as a JSON object.
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: submissionId
in: path
description: ID of module submission to update
required: true
schema:
type: string
- name: transformName
in: query
description: Transform to apply to module for input. Transform must be configured and designated for for input. Available transform types may be listed via the /transforms endpoint.
schema:
type: string
- name: replaceData
in: query
description: Whether to completely replace the submission data with the object passed in "data". This option is available to "Administrator" users only.
schema:
type: boolean
default: false
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdatedSubmissionRequest'
responses:
'200':
description: Submission updated
content:
application/json:
schema:
$ref: '#/components/schemas/SavedSubmissionResponse'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
tags:
- Submissions
summary: Delete Module Submission
operationId: deleteModuleSubmission
description: >
Deletes a single module submission based on the ID supplied. Note that module submissions are soft-deleted (marked deleted, but not removed).
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: submissionId
in: path
description: ID of module submission to delete
required: true
schema:
type: string
- name: destroy
in: query
description: Whether to hard delete the submission from database. Value of 'destroy=true' will delete the submission. This option requires administrator privileges. Once deleted, the submission cannot be retrieved back.
schema:
type: boolean
default: false
responses:
'204':
description: Submission deleted
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/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](#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](#section/Cloud-Storage-Delivery) to the rendered PDF (and optionally base 64 data).
### Authorization Required:
- See Submission Access ([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'
'/modules/{moduleId}/submissions/{submissionId}/restore':
post:
x-unqork-service: true
tags:
- Submissions
summary: Restore a Deleted Module Submission
operationId: restoreDeletedModuleSubmission
description: >
Restore a soft-deleted submission.
### Authorization Required:
- See Submission Access ([Submission Access](#submission-access))
parameters:
- $ref: '#/components/parameters/ModuleID'
- name: submissionId
in: path
description: ID of module submission to restore
required: true
schema:
type: string
responses:
'204':
description: Successfully Restored
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](#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](#section/Cloud-Storage-Delivery) to the rendered PDF (and optionally base 64 data).
### Authorization Required:
- See Submission Access ([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
# --- truncated at 32 KB (194 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/unqork/refs/heads/main/openapi/unqork-customer-api-openapi.yml