FormKiQ Core Reference Guide

Table of Contents

1. Introduction

FormKiQ

FormKiQ Core is an Open Source Headless Document Management System (DMS) that runs completely in YOUR Amazon Web Services (AWS) Cloud.

You can use FormKiQ to power:

  • Easy storage of Documents / Form data from your website

  • Quick Tagging and Organization of your Documents

  • Flexible integration into existing application or building custom workflows

FormKiQ is built for any size organization, from personal websites to large, enterprise organizations requiring full control of any number of internal and external documents.

FormKiQ Core is built using AWS Serverless services

This means that there are no servers for you to maintain or manage, and all of your data stays within your AWS cloud.

1.1. Features

Please visit our website to see the full list of features.

✅ API First (FormKiQ API) and Cloud-Native Architecture

✅ Easy Integration with Existing Applications

✅ Built Using Serverless Services (no servers to maintain or manage)

✅ Supports Unlimited Document Tagging & Versioning

✅ Document Processing Through Subscribing to Document Events

✅ Supports Both Multi-Tenant and Multi-Instance

✅ Includes an Intuitive User Interface (FormKiQ Console) for Document Management

FormKiQ has an enterprise edition that provides support and battle-tested enterprise add-on modules.

To learn more about FormKiQ Core, please visit https://github.com/formkiq/formkiq-core.

To learn more about FormKiQ Enterprise, please visit https://formkiq.com.

2. Architecture

2.1. Overview

Architecture

FormKiQ has been architected using Amazon Web Services (AWS) serverless technologies. This provides several benefits:

✅ Only pay AWS for usage (all services come with a generous monthly free tier)

✅ Easily scales to thousands of concurrent requests

✅ No servers to maintain or manage

2.2. Components

  • Data Storage - The data storage stores the document’s data and any metadata (tags, related documents) attached to the document.

  • API - API is an interface to the documents that provides a well-defined method for working with documents.

  • Processing - The processing component sit in between the API and data storage component and translates requests between the two components.

  • Authentication - Ensures authentication and authorization for access to the documents.

  • Document Events - FormKiQ is designed using an Event driven architecture using AWS Messaging services for easily integration into any system.

2.2.1. Data Storage

The data storage component divides into two parts, the document storage and the document metadata storage.

Document Storage

Document storage is done using Amazon’s S3 service. S3 provides industry-leading data durability and data protection for all of your documents.

Description of S3 Buckets:

Bucket

Description

Staging

A temporary holding place for documents waiting for processing

Documents

The permanent post-processing document storage
Metadata Storage

Each document’s metadata is stored in Amazon’s NoSQL database DynamoDB. DynamoDB is a fast, flexible NoSQL database service for single-digit millisecond performance at any scale. It is also fully-managed by AWS, so there are no database servers to manage.

Description of DynamoDB Tables:

Bucket

Description

Documents

Stores a record of all documents along with all metadata and tenant information

Caching

A storage for temporary data

2.2.2. API

The API is built using Amazon API Gateway. Amazon API Gateway is a fully-managed service that handles all of the tasks involved in accepting and processing up to hundreds of thousands of concurrent API calls, including traffic management, CORS support, authorization and access control, throttling, and monitoring.

FormKiQ deploys with two APIs. One API is deployed with JWT authentication using Amazon Cognito as the JWT authorizer.

A second identical API is deployed using AWS Identity and Access Management (IAM).

The JWT-authenticated API is great for handling users requests, while the IAM-authenticated API is great for machine-to-machine or backend processing.

NOTE All endpoints require either Cognito / IAM Authentication unless the URL starts with /public; the /public endpoint can be used to allow publicly-submitted documents such as web forms.

2.2.3. Processing

All processing components are built using AWS Lambda. AWS Lambda allows the processing of documents/requests without managing servers or clusters. It also automatically scales to the capacity you need. With built-in fault tolerance, AWS Lambda is designed to provide high availability and to be resilient to failure.

2.2.4. Authentication

Security is of the utmost importance for any system. However, flexibility is required to be able to integrate securely with other systems. This is why both JSON Web Tokens (JWTs) and AWS Identity and Access Management (IAM) are supported methods for authentication.

JSON Web Tokens (JWTs)

JSON Web Tokens (JWTs) as a part of OpenID Connect (OIDC) and OAuth 2.0 frameworks to restrict client access to the APIs.

Amazon Cognito is used as the default JWT authorizer to ensure the JWT tokens are authentic and valid. However, any other JWT authorizer can be used.

AWS Identity and Access Management (IAM)

AWS Identity and Access Management (IAM) is the access control used across all of AWS services. Using IAM policies, one could provide a service the ability to call any API. This allows for an automated method for backend services to integrate with the FormKiQ API, with no need to retrieve a JWT token first.

2.2.5. Document Events

Document events are a powerful feature of FormKiQ Core. These events allow operations to be triggered on documents automatically, whenever a change occurs. For example, when a document is created, a document event can be triggered to perform one or many actions, such as:

  • sending an email notification

  • scanning for viruses

  • inserting data into a database

  • etc.

Document event are created and sent through Amazon Simple Notification Service (SNS). Amazon SNS is a messaging service that can be used for application-to-application communication. FormKiQ Core uses it as a publish/subscribe service, where applications can listen to the SNS service and be notified about different document events.

FormKiQ Core creates a single SnsDocumentEvent topic where all document events are sent. You can then use Amazon SNS subscription filter policies to set up actions for a specific type of event.

FormKiQ Core provides the following message attributes that you can filter on:

Message Attribute

Possible Value(s)

Description

type

create, delete, update

Document Event(s) for create, update, or delete document

siteId

default, (custom siteId)

Site Tenant Document Event was created in

See https://docs.aws.amazon.com/sns/latest/dg/sns-subscription-filter-policies.html

3. Installation

FormKiQ was built using the AWS Serverless Application Model (SAM) framework.

FormKiQ Core uses AWS resources, including DynamoDB, CloudFront, Lambda functions, and API Gateway. These resources are defined in the template.yaml file in this project. You can customize FormKiQ by updating the template and adding AWS resources through the same deployment process that updates your application code.

A Note about AWS Accounts: we recommend creating a dev or staging account as well as a prod account, as opposed to deploying two instances of FormKiQ with different stages/environments. This isn’t due to any issues with running two FormKiQ instances, but to help better separate your non-prod integration from your production instance.

To have more than one account, you can set up a new AWS account to be your organization management account, and then use AWS Organizations to add two or more additional accounts, one for each stage/environment you plan to use. If you have an existing AWS account with active AWS services/resources, you should import that into a new management account, rather than use that account as your management account, as AWS Best Practices is to not run workloads in your management account.

3.1. Download

The latest version of FormKiQ Core can be found on the FormKiQ Core Releases page on GitHub. Download the source code (tar.gz or zip) to your local computer and expand/unzip into its own folder, formkiq-core-x.x.x.

3.2. Deploy

The Serverless Application Model Command Line Interface (SAM CLI) is an extension of the AWS CLI that adds functionality for deploying serverless applications.

To use SAM CLI, you will need to install the following tools:

To deploy FormKiQ Core for the first time, run the following in your shell from the root of this formkiq-core-x.x.x folder:

sam deploy --guided --capabilities CAPABILITY_IAM CAPABILITY_AUTO_EXPAND CAPABILITY_NAMED_IAM

The command will package and deploy your application to AWS, with a series of prompts:

  • Stack Name: the name of the stack to deploy to CloudFormation; this should be unique to your account and region, and a good starting point would be formkiq-core-<AppEnvironment> where AppEnvironment matches your installation environment, e.g. prod, dev, test

  • AWS Region: the AWS region you want to deploy your app to

  • AdminEmail: the Administration Email you want FormKiQ to use

  • AppEnvironment: your installation environment, e.g. prod, dev, test; must be unique per account

  • EnablePublicUrls: whether to Enable /public/ urls.

  • PasswordMinimumLength: the minimum Password Length for User Accounts

  • PasswordRequireLowercase: whether at least one lowercase letter is required in User Passwords

  • PasswordRequireNumbers: whether at least one number is required in User Passwords

  • PasswordRequireSymbols: whether at least one symbol is required in User Passwords

  • PasswordRequireUppercase: whether at least one uppercase letter is required in User Passwords

  • Confirm changes before deploy: if set to yes, any change sets will be shown to you before execution for manual review; if set to no, the AWS SAM CLI will automatically deploy application changes

  • Allow SAM CLI IAM role creation: FormKiQ Core’s AWS SAM templates create AWS IAM roles required for the AWS Lambda function(s) included to access AWS services; the permissions are passed in by the sam deploy command above, so this value should be set to "Y"

  • Save arguments to samconfig.toml: if set to "Y", your choices will be saved to a configuration file inside the project, so that in the future you can just re-run sam deploy without parameters to deploy changes to your application

Once you have set all of these options, SAM CLI will create a changeset and will display a list of all actions that will be performed as part of the changeset. If you have set "confirm changes before deploy" to "Y", you will then be asked whether or nor to deploy this changeset. Choose "Y" to complete the installation.

Once the FormKiQ Core stack has been deployed, you will be able to find your two available API Gateway Endpoint URLs (HTTP/Cognito and IAM) in the output values displayed after deployment.

3.2.1. Outputs

After the FormKiQ Cloudformation Stack completes, output values from the deployment are made available in the CloudFormation Outputs and in the SSM Parameter Store. Below you’ll find a description of the outputs.

CloudFormation Outputs

Key

Description

CognitoClientId

Cognito Client Id

CognitoUserPoolId

Cognito User Pool Id

ConsoleUrl

The URL for the FormKiQ Console

FormKiQVersion

FormKiQ Version

HttpApiUrl

The URL for the API endpoint that uses Cognito authorization

IamApiUrl

The URL for the API endpoint that uses IAM authorization

SSM Parameter Store

SSM parameters made it easy for applications to automatically look up FormKiQ configuration settings. All configuration keys start with /formkiq/{AppEnvironment}

Parameter

Description

api/DocumentsHttpUrl

The URL for the API endpoint that uses Cognito authorization

api/DocumentsIamUrl

The URL for the API endpoint that uses IAM authorization

cognito/AdminGroup

Cognito Admin Group

cognito/IdentityPoolId

Cognito Identity Pool

cognito/UserPoolArn

Cognito User Pool Arn

cognito/UserPoolClientId

Cognito User Pool Client

cognito/UserPoolId

Cognito User Pool

cognito/UserPoolProviderName

Cognito User Pool Provider Name

cognito/UserPoolProviderUrl

Cognito User Pool Provider URL

console/AdminEmail

Console Admin Email

console/Url

The URL for the FormKiQ Console

console/version

Console Version

dynamodb/CacheTableName

DynamoDB Cache table name

dynamodb/DocumentsTableName

DynamoDB Documents table name

iam/ApiGatewayInvokeGroup

API Gateway Group that allows invoking of endpoints

iam/ApiGatewayInvokeGroupArn

API Gateway Group Arn that allows invoking of endpoints

iam/ApiGatewayInvokeRole

API Gateway Role that allows invoking of endpoints

iam/ApiGatewayInvokeRoleArn

API Gateway Role Arn that allows invoking of endpoints

lambda/ConsoleInstaller

Lambda for Console Installation

lambda/DocumentsApiRequests

Lambda for processing API Requests

lambda/DocumentsUpdateObject

Lambda for processing Document Update Events

lambda/StagingCreateObject

Lambda for processing Staging Document Create Events

region

Deployment Region

s3/Console

Console S3 Bucket

s3/ConsoleArn

Console S3 Bucket Arn

s3/ConsoleDomainName

Console S3 Bucket Domain Name

s3/ConsoleRegionalDomainName

Console S3 Bucket Regional Domain Name

s3/DocumentsS3Bucket

Documents S3 Bucket Name

s3/DocumentsStageS3Bucket

Documents Staging S3 Bucket Name

sns/SnsDocumentsCreateEventTopicArn

SNS Topic for Document Create Events

sns/SnsDocumentsDeleteEventTopicArn

SNS Topic for Document Delete Events

sns/SnsDocumentsUpdateEventTopicArn

SNS Topic for Document Update Events

sqs/DocumentsUpdateArn

SQS ARN for processing Document Update Events

sqs/DocumentsUpdateUrl

SQS URL for processing Document Update Events

version

FormKiQ Stacks Version

3.3. Uninstall

FormKiQ uses AWS CloudFormation to provision all resources. Uninstalling FormKiQ is as easy as logging into the AWS CloudFormation Console and deleting the formkiq-core stack.

Alternatively, you can use the AWS CLI. Assuming you used the suggested stack name (formkiq-core-<AppEnvironment>) for the stack name, you can run the following:

aws cloudformation delete-stack --stack-name formkiq-core-&lt;AppEnvironment&gt;

3.4. Upgrading

FormKiQ is designed to be N-1 compatible for updates, with automatic upgrades of database schema and other components whenever possible.

4. Building From Source

FormKiQ-Core was built using Java and JavaScript languages. In order to build from source you will need to install the development tools listed below.

Required Development Tools

Running Build

FormKiQ-Core uses Gradle as the main build tool.

To compile:

./gradlew clean build

Build configuration is controlled through the gradle.properties file located in the root folder.

Gradle parameters

# gradle.properties
#
# testregion - the name of the AWS Region to deploy to (us-east-1,us-east-2,etc)
# testappenvironment - the name of the FormKiQ App Environment (test,prd,dev)

# testprofile - the name of the AWS CLI profile (https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html)
# testadminemail - an email address to use for the administration account
#

testregion & testappenvironment are required for the ./gradlew build task.

After a successful build, all of the artifacts will be placed in the build/distributions/formkiq-core/formkiq-core-${version}.zip.

5. S3 Buckets

FormKiQ uses the Amazon Simple Storage Service (Amazon S3) as the backend object store for all documents. Amazon S3 is a manage object storage service that offers industry-leading scalability, data availability, security, and performance.

Amazon S3 is a cost-effective storage solution that’s easy-to-use, supports multiple storage classes for cost optimization, and allows for fine-tuned access controls to meet specific business, organizational, and compliance requirements.

By default FormKiQ installs with two S3 buckets.

Bucket

Description

Staging

A temporary holding place for documents waiting for processing

Documents

The permanent post-processing document storage

5.1. S3 Lifecycle

S3 Architecture

Documents can be added to S3 via the FormKiQ API or directly to the Staging S3 bucket. While it is recommended to only use the API for your standard workflow, it can be advantageous to add documents directly to the Staging S3 bucket, for operations such as initial document migration.

When a document is added to the Staging S3 bucket, an S3 object create event is created that calls the Document Create AWS Lambda. The Document Create Lambda writes a record to Amazon DynamoDB, and moves the document to the Documents S3 bucket.

Once the document is added to the Documents S3 bucket, another S3 event is created which adds a message to the Update Document Amazon SQS queue. An Update Document Lambda is listening to the Update Document SQS queue and adds and updates document metadata whenever an event is added to the queue. Any S3 object tags that have been specified will also be included as document metadata.

NOTE: Each time a document is create or updated the AWS Lambda function also posts a message to Amazon Simple Notification Service, which can be used to trigger additional document processing.

5.2. Using S3 Directly (without the API)

For initial document migration or other occasional uses, the Staging S3 bucket does allow direct uploads.

WARNING: Writing files directly to the Documents S3 bucket (i.e., not the Staging bucket) is NOT supported and may cause stability issues.

5.2.1. S3 Layout

FormKiQ is a multi-tenant application, so a specific S3 key structure is used to identify which tenant owns the document.

Documents added to ROOT

Any documents that are added to the "ROOT" of the S3 bucket, e.g. a document with S3 key of document1.txt, are assumed to be part of the DEFAULT siteId.

Documents can also be added to the DEFAULT siteId if the key starts with default, e.g. S3 key of default/document1.txt.

Documents added to SiteId

Documents can be added to a specific siteId by having that siteId as the first "folder" of they key, e.g. S3 key of group1/document1.txt will add the document1.txt to the group1 siteId.

Documents with a PATH

As of version 1.7.0, documents can be added and have a path tag automatically created. Following the same pattern as above EXCEPT the S3 key MUST start with either default or the siteId path.

For examples:

S3 key of default/dir1/dir2/document1.txt will add a document with a path tag of dir1/dir2/document1.txt to the default siteId.

S3 key of group1/dir1/dir2/document2.txt will add a document with a path tag of dir1/dir2/document2.txt to the group1 siteId.

5.2.2. Adding a Document with Tags

As of version 1.7.0, you can use the S3 Layout describe above if the S3 key ends in .fkb64

For example creating the following JSON and saving it as document1.fkb64 in the ROOT of the Staging bucket will add the content field as a document in the default siteId.

Required fields are marked below.

{
  "path": "document1.txt",
  "userId": "joesmith", // <required>
  "contentType": "text/plain", // <required>
  "isBase64": true, // <required>
  "content": "dGhpcyBpcyBhIHRlc3Q=", // <required>
  "tags": [
    {
      "key": "category",
      "value": "document"
    },
    {
      "key": "user",
      "values": ["1", "2"]
    }
  ]
}

6. Webhooks

Many services today allow you to uses webhooks to notify your application when an event happens within the service. For example, Stripe allows you to specify webhooks to notify your application when a specific event happens within your Stripe account.

With FormKiQ Core, you can create webhook endpoints to receive and store event notifications from other services. Using the /webhooks API (or from the FormKiQ Console), you can create a webhook and then enter that webhook in Stripe or other supporting services to immediately start receiving notifications.

FormKiQ Core also allows you to take this one step further: using the Document Events that are created every time a webhook notification is received, you can easily write custom code that is automatically executed.

7. Multi-Tenant

FormKiQ Core supports usage as a multi-tenant application. This can be used for internal departments or teams, or for external clients. During deployment, a "default" SiteId is created; all documents are stored in that tenant by default.

To create another SiteId is as simple as adding a new Cognito group to the user pool

Creating a Cognito Group with the same name as the SiteId but ending in "_read" will create a read-only group. The users in this group will have read-only access to documents within that SiteId.

Each API request has an optional "SiteId" parameter to specify which SiteId you would like to use.

NOTE: This parameter is only needed if a user belongs to multiple SiteIds or if the user is in the "Admins" Group (full access) and wants to perform an operation in a SiteId other than "default". This allows groups such as external clients to access documents without requiring knowledge of their SiteId.

8. API Reference

All endpoints require either Cognito / IAM Authentication unless the URL starts with /public.

Public URLs are disabled by default and can be enabled through the CloudFormation installation.

8.1.1. POST /search

Description

Document search query request; documents are searched primarily using a document tag key and optional tag value, while an optional documentIds parameter is also available in the DocumentSearchBody to filter within up to 100 documentIds

Parameters
Body Parameter
Name Description Required Default Pattern

DocumentSearchBody

DocumentSearchBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

limit

Limit Results

-

null

next

Next page of results token

-

null

previous

Previous page of results token

-

null
Return Type

DocumentSearchResults

Content Type

  • application/json

Responses
Table 1. http response codes
Code Message Datatype

200

200 OK

DocumentSearchResults

8.2. Document Tags

8.2.1. GET /documents/{documentId}/tags

Description

Get a listing of a document’s tags

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

limit

Limit Results

-

null

next

Next page of results token

-

null

previous

Previous page of results token

-

null
Return Type

DocumentItemsTags

Content Type

  • application/json

Responses
Table 2. http response codes
Code Message Datatype

200

200 OK

DocumentItemsTags

8.2.2. POST /documents/{documentId}/tags

Description

Add a single tag to a document; endpoint also accepts a different body parameter for adding multiple tags at one time

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Body Parameter
Name Description Required Default Pattern

DocumentItemTag

DocumentItemTag

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 3. http response codes
Code Message Datatype

201

201 CREATED

<<>>

8.2.3. POST /documents/{documentId}/tags

Description

Add multiple tags to a document; endpoint also accepts a different body parameter for adding a single tag

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Body Parameter
Name Description Required Default Pattern

DocumentTagsPost

DocumentTagsPost

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 4. http response codes
Code Message Datatype

201

201 CREATED

<<>>

8.2.4. DELETE /documents/{documentId}/tags/{tagKey}

Description

Delete a document tag by using its key; if a document has multiple values for this tag key, ALL values for that tag key will be deleted

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null

tagKey

Tag Key

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 5. http response codes
Code Message Datatype

200

200 OK

<<>>

8.2.5. GET /documents/{documentId}/tags/{tagKey}

Description

Get a document tag by using its key

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null

tagKey

Tag Key

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentItemTag

Content Type

  • application/json

Responses
Table 6. http response codes
Code Message Datatype

200

200 OK

DocumentItemTag

8.2.6. PUT /documents/{documentId}/tags/{tagKey}

Description

Update any and all values of a document tag, by using its key; you can supply one tag value or a list of tag values in the request body

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null

tagKey

Tag Key

X

null
Body Parameter
Name Description Required Default Pattern

DocumentItemTagValueBody

DocumentItemTagValueBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 7. http response codes
Code Message Datatype

200

200 OK

<<>>

8.2.7. DELETE /documents/{documentId}/tags/{tagKey}/{tagValue}

Description

Delete a specific document tag’s key/value combination; the request will be ignored if there is no valid key/value combination found

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null

tagKey

Tag Key

X

null

tagValue

Tag Key Value

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 8. http response codes
Code Message Datatype

200

200 OK

<<>>

8.3. Documents

8.3.1. GET /documents/{documentId}/content

Description

Get a document’s contents

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

versionId

Version Identifier

-

null
Return Type

DocumentContent

Content Type

  • application/json

Responses
Table 9. http response codes
Code Message Datatype

200

200 OK

DocumentContent

8.3.2. DELETE /documents/{documentId}

Description

Delete a document

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 10. http response codes
Code Message Datatype

200

200 OK

<<>>

8.3.3. GET /documents/{documentId}

Description

Retrieves a document’s details, i.e., metadata

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentItem

Content Type

  • application/json

Responses
Table 11. http response codes
Code Message Datatype

200

200 OK

DocumentItem

8.3.4. PATCH /documents/{documentId}

Description

Update a document’s details, i.e., metadata

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Body Parameter
Name Description Required Default Pattern

DocumentBody

DocumentBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentPostResponse

Content Type

  • application/json

Responses
Table 12. http response codes
Code Message Datatype

200

200 OK

DocumentPostResponse

8.3.5. GET /documents/{documentId}/upload

Description

Returns a URL that can be used to upload documents for a specific documentId (required for documents larger than 5 MB)

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

contentLength

Indicates the size of the entity-body

-

null

duration

Indicates the number of hours request is valid for

X

null
Return Type

DocumentUrl

Content Type

  • application/json

Responses
Table 13. http response codes
Code Message Datatype

200

200 OK

DocumentUrl

8.3.6. GET /documents/{documentId}/url

Description

Returns a URL for the document’s contents that expires (default is 48 hours)

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

versionId

Version Identifier

-

null

duration

Indicates the number of hours request is valid for

X

null
Return Type

DocumentUrl

Content Type

  • application/json

Responses
Table 14. http response codes
Code Message Datatype

200

200 OK

DocumentUrl

8.3.7. GET /documents/{documentId}/versions

Description

Get a listing of document content versions

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

next

Next page of results token

-

null
Return Type

DocumentItemsVersions

Content Type

  • application/json

Responses
Table 15. http response codes
Code Message Datatype

200

200 OK

DocumentItemsVersions

8.3.8. GET /documents

Description

Returns a list of the most recent documents added, ordered by inserted, descending

Parameters
Query Parameters
Name Description Required Default Pattern

date

Fetch documents inserted on a certain date (yyyy-MM-dd)

-

null

tz

UTC offset to apply to date parameter (IE: -0600)

-

null

next

Next page of results token

-

null

previous

Previous page of results token

-

null

siteId

Site Identifier

-

null

limit

Limit Results

-

null
Return Type

DocumentItemsResults

Content Type

  • application/json

Responses
Table 16. http response codes
Code Message Datatype

200

200 OK

DocumentItemsResults

8.3.9. POST /documents

Description

Creates a new document; body may include document content if less than 5 MB

Parameters
Body Parameter
Name Description Required Default Pattern

DocumentBody

DocumentBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentPostResponse

Content Type

  • application/json

Responses
Table 17. http response codes
Code Message Datatype

201

201 CREATED

DocumentPostResponse

8.3.10. GET /documents/upload

Description

Returns a URL that can be used to upload document content and create a new document; required to add content that is larger than 5 MB

Parameters
Query Parameters
Name Description Required Default Pattern

path

The upload file's path

-

null

siteId

Site Identifier

-

null

contentLength

Indicates the size of the entity-body

-

null

duration

Indicates the number of hours request is valid for

X

null
Return Type

DocumentUrl

Content Type

  • application/json

Responses
Table 18. http response codes
Code Message Datatype

200

200 OK

DocumentUrl

POST /documents/upload

Description

Returns a URL that can be used to upload document content and create a new document; required to add content that is larger than 5 MB

Parameters
Body Parameter
Name Description Required Default Pattern

DocumentUploadBody

DocumentUploadBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

duration

Indicates the number of hours request is valid for

-

null
Return Type

DocumentPostResponse

Content Type

  • application/json

Responses
Table 19. http response codes
Code Message Datatype

201

201 CREATED

DocumentPostResponse

8.4. EnterpriseAPI

GET /documents/{documentId}/ocr

Description

Get Document optical character recognition (OCR) result; if exists. ONLY available with FormKiQ Enterprise

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentOcr

Content Type

  • application/json

Responses
Table 20. http response codes
Code Message Datatype

200

200 OK

DocumentOcr

POST /documents/{documentId}/ocr

Description

Document optical character recognition (OCR) request; extract text and data from a document. ONLY available with FormKiQ Enterprise

Parameters
Path Parameters
Name Description Required Default Pattern

documentId

Document Identifier

X

null
Body Parameter
Name Description Required Default Pattern

OcrBody

OcrBody

-
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentOcrResult

Content Type

  • application/json

Responses
Table 21. http response codes
Code Message Datatype

200

200 OK

DocumentOcrResult

GET /tagSchemas

Description

Returns the list of tagSchemas

Parameters
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null

limit

Limit Results

-

null

next

Next page of results token

-

null

previous

Previous page of results token

-

null
Return Type

TagSchemas

Content Type

  • application/json

Responses
Table 22. http response codes
Code Message Datatype

200

200 OK

TagSchemas

POST /tagSchemas

Description

Creates a new TagSchema

Parameters
Body Parameter
Name Description Required Default Pattern

TagSchemaBody

TagSchemaBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

TagSchemaPostResponse

Content Type

  • application/json

Responses
Table 23. http response codes
Code Message Datatype

201

201 CREATED

TagSchemaPostResponse

400

400 BAD REQUEST

ErrorsResponse

DELETE /tagSchemas/{tagSchemaId}

Description

Delete a TagSchema

Parameters
Path Parameters
Name Description Required Default Pattern

tagSchemaId

Tag Schema Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 24. http response codes
Code Message Datatype

200

200 OK

<<>>

GET /tagSchemas/{tagSchemaId}

Description

Retrieves a TagSchema’s details, i.e., metadata

Parameters
Path Parameters
Name Description Required Default Pattern

tagSchemaId

Tag Schema Identifier

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

TagSchema

Content Type

  • application/json

Responses
Table 25. http response codes
Code Message Datatype

200

200 OK

TagSchema

8.5. Miscellaneous

GET /sites

Description

Returns the list of sites that the user has access to

Parameters
Return Type

Sites

Content Type

  • application/json

Responses
Table 26. http response codes
Code Message Datatype

200

200 OK

Sites

GET /version

Description

Return the version of FormKiQ

Parameters
Return Type

Version

Content Type

  • application/json

Responses
Table 27. http response codes
Code Message Datatype

200

200 OK

Version

POST /public/documents

Description

Allows unauthenticated creation of new documents; must be enabled during installation (disabled by default)

Parameters
Body Parameter
Name Description Required Default Pattern

DocumentBody

DocumentBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentId

Content Type

  • application/json

Responses
Table 28. http response codes
Code Message Datatype

201

201 CREATED

DocumentId

POST /public/webhooks/{webhooks+}

Description

Receives an incoming public post to a specified webhook and creates a document based on the data sent; must be enabled during installation (disabled by default)

Parameters
Path Parameters
Name Description Required Default Pattern

webhooks+

Web Hook Param

X

null
Body Parameter
Name Description Required Default Pattern

body

[object]

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentId

Content Type

  • application/json

Responses
Table 29. http response codes
Code Message Datatype

200

200 OK

DocumentId

8.6. Webhooks

POST /private/webhooks/{webhooks+}

Description

Receives an incoming private webhook and creates a document based on the webhook’s body; requires authentication

Parameters
Path Parameters
Name Description Required Default Pattern

webhooks+

Web Hook Param

X

null
Body Parameter
Name Description Required Default Pattern

body

[object]

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

DocumentId

Content Type

  • application/json

Responses
Table 30. http response codes
Code Message Datatype

200

200 OK

DocumentId

GET /webhooks

Description

Returns a list of webhooks; each webhook’s id can be provided to an external service, allowing data to be sent, received, and processed via that webhook

Parameters
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

WebhookResults

Content Type

  • application/json

Responses
Table 31. http response codes
Code Message Datatype

200

200 OK

WebhookResults

POST /webhooks

Description

Create a new webhook; once created, a webhook’s id can be provided to an external service, allowing data to be sent, received, and processed via that webhook

Parameters
Body Parameter
Name Description Required Default Pattern

WebhookBody

WebhookBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

WebhookPostResponse

Content Type

  • application/json

Responses
Table 32. http response codes
Code Message Datatype

201

201 CREATED

WebhookPostResponse

DELETE /webhooks/{webhookId}

Description

Deletes a webhook; this will disable sending, receiving, or processing of data from external services to this webhook

Parameters
Path Parameters
Name Description Required Default Pattern

webhookId

Web Hook Param

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 33. http response codes
Code Message Datatype

200

200 OK

<<>>

GET /webhooks/{webhookId}

Description

Returns a webhook’s details, i.e., its metadata

Parameters
Path Parameters
Name Description Required Default Pattern

webhookId

Web Hook Param

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

Webhook

Content Type

  • application/json

Responses
Table 34. http response codes
Code Message Datatype

200

200 OK

Webhook

PATCH /webhooks/{webhookId}

Description

Updates a webhook’s details, i.e., its metadata

Parameters
Path Parameters
Name Description Required Default Pattern

webhookId

Web Hook Param

X

null
Body Parameter
Name Description Required Default Pattern

WebhookBody

WebhookBody

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 35. http response codes
Code Message Datatype

200

200 OK

<<>>

GET /webhooks/{webhookId}/tags

Description

Get a webhook’s tags

Parameters
Path Parameters
Name Description Required Default Pattern

webhookId

Web Hook Param

X

null
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

WebhookTags

Content Type

  • application/json

Responses
Table 36. http response codes
Code Message Datatype

200

200 OK

WebhookTags

POST /webhooks/{webhookId}/tags

Description

Add a tag to a webhook

Parameters
Path Parameters
Name Description Required Default Pattern

webhookId

Web Hook Param

X

null
Body Parameter
Name Description Required Default Pattern

DocumentItemTag

DocumentItemTag

X
Query Parameters
Name Description Required Default Pattern

siteId

Site Identifier

-

null
Return Type

-

Responses
Table 37. http response codes
Code Message Datatype

201

200 OK

<<>>

9. Models

9.1. DocumentAction

Document action

Field Name Required Type Description Format

type

String

Type of action (supported values: ocr)

parameters

DocumentAction_parameters

9.2. DocumentActionParameters

Field Name Required Type Description Format

ocrParseTypes

String

OCR Parse types - TEXT, FORMS, TABLES

9.3. DocumentBody

Field Name Required Type Description Format

tagSchemaId

String

Tag Schema Id

path

String

Path or Name of document

contentType

String

Document Content-Type

isBase64

Boolean

Is Content Base64 encoded

content

X

String

Document content

tags

List of [WebhookBody_tags_inner]

List of tags

actions

List of DocumentAction

List of document actions

documents

List of [DocumentBody_documents_inner]

List of related documents

9.4. DocumentBodyDocumentsInner

Field Name Required Type Description Format

path

String

Path or Name of document

contentType

String

Document Content-Type

isBase64

Boolean

Is Content Base64 encoded

content

String

Document content

tags

List of [WebhookBody_tags_inner]

List of tags

9.5. DocumentContent

Field Name Required Type Description Format

content

String

Document content

contentUrl

String

Url to document content

contentType

String

Document Content-Type

isBase64

Boolean

Is Content Base64 encoded

9.6. DocumentId

Field Name Required Type Description Format

documentId

X

UUID

Document Identifier

uuid

siteId

String

Site Identifier

9.7. DocumentItem

Field Name Required Type Description Format

next

String

Next page of results token

previous

String

Previous page of results token

siteId

String

Site Identifier

path

X

String

Path or Name of document

insertedDate

Date

Inserted Timestamp

date-time

checksum

String

Document checksum, changes when document file changes

documentId

X

UUID

Document Identifier

uuid

contentType

String

Document Content-Type

userId

String

User who added document

contentLength

Integer

Document size

versionId

String

Document version

belongsToDocumentId

String

Parent Document Identifier

documents

List of [DocumentItem_documents_inner]

List of related documents

9.8. DocumentItemDocumentsInner

Field Name Required Type Description Format

path

String

Path or Name of document

insertedDate

Date

Inserted Timestamp

date-time

checksum

String

Document checksum, changes when document file changes

documentId

UUID

Document Identifier

uuid

contentType

String

Document Content-Type

userId

String

User who added document

contentLength

Integer

Document size

versionId

String

Document version

belongsToDocumentId

String

Parent Document Identifier

9.9. DocumentItemResult

Field Name Required Type Description Format

siteId

String

Site Identifier

path

String

Path or Name of document

insertedDate

Date

Inserted Timestamp

date-time

checksum

String

Document checksum, changes when document file changes

documentId

UUID

Document Identifier

uuid

contentType

String

Document Content-Type

userId

String

User who added document

contentLength

Integer

Document size

versionId

String

Document version

9.10. DocumentItemTag

Field Name Required Type Description Format

insertedDate

String

Inserted Timestamp

documentId

String

Document Identifier

type

String

Tag type

userId

String

User who added document

value

X

String

Tag value

values

List of [string]

Tag values

key

X

String

Tag key

9.11. DocumentItemTagValueBody

Field Name Required Type Description Format

value

String

Tag value

values

List of [string]

Tag values

9.12. DocumentItemVersion

Field Name Required Type Description Format

versionId

X

String

Document version

lastModifiedDate

String

Last modified date

9.13. DocumentItemsResults

Field Name Required Type Description Format

next

String

Next page of results token

previous

String

Previous page of results token

documents

List of DocumentItemResult

List of documents

9.14. DocumentItemsTags

Field Name Required Type Description Format

next

String

Next page of results token

previous

String

Previous page of results token

tags

List of DocumentItemTag

List of tags

9.15. DocumentItemsVersions

Field Name Required Type Description Format

next

String

Next page of results token

versions

List of DocumentItemVersion

List of document versions

9.16. DocumentOcr

Field Name Required Type Description Format

data

String

OCR text result

ocrEngine

String

The OCR technique used

ocrStatus

String

The status of the OCR request

contentType

String

Document Content-Type

isBase64

Boolean

Is Content Base64 encoded

userId

String

User who requested the OCR

documentId

UUID

Document Identifier

uuid

9.17. DocumentOcrResult

Field Name Required Type Description Format

message

String

OCR processing message

9.18. DocumentPostResponse

Field Name Required Type Description Format

documentId

UUID

Document Identifier

uuid

siteId

String

Site Identifier

uploadUrl

String

Url to upload document to

documents

List of [DocumentPostResponse_documents_inner]

List of related documents

9.19. DocumentPostResponseDocumentsInner

Field Name Required Type Description Format

documentId

String

Document Identifier

uploadUrl

String

Url to upload document to

9.20. DocumentSearchBody

Document search tag criteria

Field Name Required Type Description Format

query

X

DocumentSearchTag

9.21. DocumentSearchItemTag

Field Name Required Type Description Format

beginsWith

String

Searches for strings that begin with

eq

String

Searches for strings that eq

eqOr

List of [string]

Searches for ANY strings that eq

key

X

String

Tag key to search

9.22. DocumentSearchMatchTag

Field Name Required Type Description Format

key

String

Tag key

value

String

Tag value

type

String

Tag type

9.23. DocumentSearchResults

Field Name Required Type Description Format

next

String

Next page of results token

previous

String

Previous page of results token

documents

List of SearchDocumentItem

List of search result documents

9.24. DocumentSearchTag

Document tag search criteria

Field Name Required Type Description Format

tag

X

DocumentSearchItemTag

documentIds

List of [string]

List of DocumentIds to filter search results on

9.25. DocumentTagsPost

Field Name Required Type Description Format

tags

X

List of DocumentItemTag

List of tags

9.26. DocumentUploadBody

Field Name Required Type Description Format

tagSchemaId

String

Tag Schema Id

path

String

Path or Name of document

tags

List of [WebhookBody_tags_inner]

List of tags

actions

List of DocumentAction

List of document actions

9.27. DocumentUrl

Field Name Required Type Description Format

documentId

String

Document Identifier

url

String

Document content url

9.28. Error

Field Name Required Type Description Format

key

String

Error Key

error

String

Error Message

9.29. ErrorsResponse

Field Name Required Type Description Format

errors

List of Error

List of errors

9.30. OcrBody

Field Name Required Type Description Format

parseTypes

List of [string]

OCR Parse types - TEXT, FORMS, TABLES

9.31. SearchDocumentItem

Field Name Required Type Description Format

siteId

String

Site Identifier

path

String

Path or Name of document

insertedDate

Date

Inserted Timestamp

date-time

checksum

String

Document checksum, changes when document file changes

documentId

UUID

Document Identifier

uuid

contentType

String

Document Content-Type

userId

String

User who added document

contentLength

Integer

Document size

versionId

String

Document version

matchedTag

DocumentSearchMatchTag

9.32. Site

Field Name Required Type Description Format

siteId

String

Site Identifier

uploadEmail

String

SiteId document upload email address

9.33. Sites

Field Name Required Type Description Format

sites

List of Site

List of sites

9.34. TagSchema

Field Name Required Type Description Format

tagSchemaId

String

name

String

userId

String

insertedDate

Date

Inserted Timestamp

date-time

tags

TagSchemaBody_tags

9.35. TagSchemaBody

Field Name Required Type Description Format

name

String

tags

TagSchemaBody_tags

9.36. TagSchemaBodyTags

Field Name Required Type Description Format

compositeKeys

List of TagSchemaCompositeKey

List of Composite Keys

required

List of TagSchemaRequired

List of Required Tags

optional

List of TagSchemaOptional

List of Optional Tags

allowAdditionalTags

Boolean

9.37. TagSchemaCompositeKey

Field Name Required Type Description Format

key

List of [string]

9.38. TagSchemaOptional

Field Name Required Type Description Format

key

String

defaultValues

List of [string]

Default values

allowedValues

List of [string]

Only valid values

9.39. TagSchemaPostResponse

Field Name Required Type Description Format

tagSchemaId

UUID

Tag Schema Identifier

uuid

9.40. TagSchemaRequired

Field Name Required Type Description Format

key

String

defaultValues

List of [string]

Default values

allowedValues

List of [string]

Only valid values

9.41. TagSchemaSummary

Field Name Required Type Description Format

tagSchemaId

String

name

String

userId

String

insertedDate

Date

Inserted Timestamp

date-time

9.42. TagSchemas

Field Name Required Type Description Format

schemas

List of TagSchemaSummary

List of Tag Schemas

next

String

previous

String

9.43. Version

Field Name Required Type Description Format

version

String

FormKiQ version

type

String

FormKiQ type

9.44. Webhook

Field Name Required Type Description Format

siteId

String

Site Identifier

name

String

Webhook name

url

String

Webhook url

insertedDate

Date

Inserted Timestamp

date-time

id

UUID

Webhook Identifier

uuid

userId

String

User who added document

9.45. WebhookBody

Field Name Required Type Description Format

name

X

String

Name of webhook

ttl

String

Webhook time to live (expiry)

enabled

String

Is webhook enabled

tags

List of [WebhookBody_tags_inner]

List of tags

9.46. WebhookBodyTagsInner

Field Name Required Type Description Format

key

String

Tag key

value

String

Tag value

9.47. WebhookPostResponse

Field Name Required Type Description Format

id

UUID

uuid

siteId

String

Site Identifier

9.48. WebhookResults

Field Name Required Type Description Format

webhooks

List of Webhook

List of webhooks

9.49. WebhookTag

Field Name Required Type Description Format

insertedDate

String

Inserted Timestamp

webhookId

String

Webhook Identifier

type

String

Tag type

userId

String

User who added document

value

X

String

Tag value

key

X

String

Tag key

9.50. WebhookTags

Field Name Required Type Description Format

next

String

Next page of results token

previous

String

Previous page of results token

tags

List of WebhookTag

List of webhook tags

10. Appendix

Please check out the website for further links, and to contact.

https://formkiq.com

https://github.com/formkiq/formkiq-core