Skip to main content

Document Reviews

Overview​

A document review is a record that a document needs decisions from people: an approval, a recommendation, an acknowledgment, or a comment. FormKiQ stores the review, every decision submitted against it, who submitted each one, and when. That gives you an auditable answer to "who signed off on this, and what did they say?"

Document reviews are part of the commercial platform. Confirm review API availability for your licensed edition and backend configuration. They are used by Business Solutions such as Contract Management.

Reviews and Workflow Queues​

FormKiQ has two ways to collect a human decision. They solve different problems and can be combined.

Workflow queue stepDocument review
PurposePause an automated process until a person chooses the next branch.Record one or more decisions about a document.
DecisionOne APPROVE or REJECT per queue step.Any number of typed decisions, with free-text outcome and comment.
CompletionThe workflow moves to the next step.The review becomes COMPLETED when enough counted decisions exist.
Who decidesUsers with access to the queue.Users with write access, optionally limited to approval groups.
In FormKiQ WebSubmit for review and the Queues list.Used by Business Solutions.

Use a workflow when the decision drives routing. Use a document review when you need several reviewers, a record of each response, or decisions that are not a simple approve or reject.

Review Structure​

A review belongs to one document. It can also be scoped to one artifact of that document by passing artifactId, so that a specific revision or rendition is what gets reviewed.

PropertyDescription
reviewCategoryRequired. A label you choose for the kind of review, such as Legal or Finance.
requiredDecisionsRequired. How many counted decisions complete the review.
countedDecisionTypesWhich decision types count toward requiredDecisions. Defaults to ["APPROVAL"].
approvalGroupsOptional. Groups whose members may submit decisions.
notificationsOptional. Email or in-app notifications queued when the review is created.
commentsOptional. Free-text notes about the review.
reviewStatusThe current status.

Review Status​

StatusMeaning
PENDINGThe review exists and is waiting for decisions.
IN_PROGRESSAt least one decision has been submitted, but the review is not yet complete.
COMPLETEDThe required number of counted decisions has been collected.
CANCELLEDThe review was cancelled before completion.
SUPERSEDEDThe review was replaced by another, usually because the document changed.
caution

COMPLETED means enough decisions were collected. It does not mean the document was approved. Read the decisions to find out what reviewers decided.

Decisions​

A decision is one response from one reviewer.

PropertyDescription
typeRequired. APPROVAL, RECOMMENDATION, ACKNOWLEDGMENT, or COMMENT.
decisionThe outcome, as text you define, for example APPROVED or REJECTED.
commentThe reviewer's explanation.

FormKiQ records each decision with its own decisionId, the submitting user, and a timestamp. Decisions are never overwritten; a reviewer who changes their mind submits another decision.

How Completion Is Counted​

Completion is a count of decision records, not of approvals and not of distinct reviewers:

  • Only decisions whose type is listed in countedDecisionTypes are counted.
  • A counted decision counts whatever its decision value is. An APPROVAL decision with the outcome REJECTED still counts.
  • Two counted decisions from the same person count as two.
  • Decision types that are not counted can still be submitted, any number of times, while the review is open. They can move a review from PENDING to IN_PROGRESS but cannot complete it.
  • When the count reaches requiredDecisions, the review becomes COMPLETED. Further decisions are rejected with 409 Conflict.

If your process requires unanimous approval, or one decision per reviewer, enforce that in your application: check the outcomes after completion, and limit who can decide with approval groups.

Who Can Decide​

Submitting a decision requires write access to the document. When the review lists approvalGroups, the caller must also belong to at least one of those groups.

Create a Review​

curl -X POST "${HTTP_API_URL}/documents/${DOCUMENT_ID}/reviews?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"review": {
"reviewCategory": "Legal",
"requiredDecisions": 2,
"countedDecisionTypes": ["APPROVAL"],
"approvalGroups": ["legal-reviewers"],
"comments": "Please review the indemnity clause."
}
}'

The response contains the reviewId.

To tell reviewers that work is waiting, include notifications. Each one needs a notificationType (EMAIL or IN_APP), a subject, and a body, and can add cc and bcc addresses. Email delivery uses the notification settings of the site.

Submit a Decision​

curl -X POST "${HTTP_API_URL}/documents/${DOCUMENT_ID}/reviews/${REVIEW_ID}/decisions?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"decision": {
"type": "APPROVAL",
"decision": "APPROVED",
"comment": "Clause 14 is acceptable as drafted."
}
}'

Follow-up Reviews​

A decision request can also carry a review object. FormKiQ then creates that follow-up review along with the decision, which is useful for staged sign-off: legal approves and, in the same call, opens the finance review. A follow-up review is created only when you supply one; completing a review does not start another automatically.

Read Reviews and Decisions​

OperationEndpoint
List the reviews for a documentGET /documents/{documentId}/reviews
Get one reviewGET /documents/{documentId}/reviews/{reviewId}
List every decision for a reviewGET /documents/{documentId}/reviews/{reviewId}/decisions

The decision list includes decisions that do not count toward completion. List endpoints are paged; pass the returned next token to continue.

Change or Cancel a Review​

PATCH /documents/{documentId}/reviews/{reviewId} updates reviewStatus, requiredDecisions, countedDecisionTypes, or comments. Properties you omit keep their values.

  • Set reviewStatus to CANCELLED to cancel a review.
  • Changing requiredDecisions or countedDecisionTypes does not change the status immediately. The new rules are applied, against all existing decisions, the next time a counted decision is submitted.

Common Patterns​

GoalConfiguration
Two approvals from the legal teamrequiredDecisions: 2, countedDecisionTypes: ["APPROVAL"], approvalGroups: ["legal-reviewers"]
Proof that a policy was readrequiredDecisions: 1, countedDecisionTypes: ["ACKNOWLEDGMENT"]
Collect comments, then one approver decidesrequiredDecisions: 1, countedDecisionTypes: ["APPROVAL"]; reviewers submit COMMENT decisions and the approver submits the APPROVAL
Staged sign-offSubmit each stage's final decision with a follow-up review for the next stage

Permissions​

OperationRequired permission
List or read reviews and decisionsREAD_DOCUMENTS
Create or update a review, submit a decisionWRITE_DOCUMENTS

See API Permissions.

Troubleshooting​

ProblemLikely causeWhat to check
409 Conflict when submitting a decisionThe review is already COMPLETED, possibly by another reviewer moments earlier.Read the review and treat the conflict as "already resolved".
A decision is refused for a user with write accessThe user is not in any of the review's approvalGroups.Compare the user's groups with the review.
A review completed although someone rejectedCompletion counts decision records, not outcomes.Read the decisions and apply your own approval rule.
A review never completesReviewers are submitting a type that is not in countedDecisionTypes.Check the review's countedDecisionTypes.
400 when creating or updating a reviewcountedDecisionTypes is empty, has duplicates, or contains an unknown type.Use only the four supported types.
Reviewers were not notifiedNo notifications were supplied, or site notification settings are incomplete.Check the request and the site's notification configuration.

API Reference​