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 step | Document review | |
|---|---|---|
| Purpose | Pause an automated process until a person chooses the next branch. | Record one or more decisions about a document. |
| Decision | One APPROVE or REJECT per queue step. | Any number of typed decisions, with free-text outcome and comment. |
| Completion | The workflow moves to the next step. | The review becomes COMPLETED when enough counted decisions exist. |
| Who decides | Users with access to the queue. | Users with write access, optionally limited to approval groups. |
| In FormKiQ Web | Submit 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.
| Property | Description |
|---|---|
reviewCategory | Required. A label you choose for the kind of review, such as Legal or Finance. |
requiredDecisions | Required. How many counted decisions complete the review. |
countedDecisionTypes | Which decision types count toward requiredDecisions. Defaults to ["APPROVAL"]. |
approvalGroups | Optional. Groups whose members may submit decisions. |
notifications | Optional. Email or in-app notifications queued when the review is created. |
comments | Optional. Free-text notes about the review. |
reviewStatus | The current status. |
Review Status
| Status | Meaning |
|---|---|
PENDING | The review exists and is waiting for decisions. |
IN_PROGRESS | At least one decision has been submitted, but the review is not yet complete. |
COMPLETED | The required number of counted decisions has been collected. |
CANCELLED | The review was cancelled before completion. |
SUPERSEDED | The review was replaced by another, usually because the document changed. |
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.
| Property | Description |
|---|---|
type | Required. APPROVAL, RECOMMENDATION, ACKNOWLEDGMENT, or COMMENT. |
decision | The outcome, as text you define, for example APPROVED or REJECTED. |
comment | The 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
typeis listed incountedDecisionTypesare counted. - A counted decision counts whatever its
decisionvalue is. AnAPPROVALdecision with the outcomeREJECTEDstill 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
PENDINGtoIN_PROGRESSbut cannot complete it. - When the count reaches
requiredDecisions, the review becomesCOMPLETED. Further decisions are rejected with409 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
| Operation | Endpoint |
|---|---|
| List the reviews for a document | GET /documents/{documentId}/reviews |
| Get one review | GET /documents/{documentId}/reviews/{reviewId} |
| List every decision for a review | GET /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
reviewStatustoCANCELLEDto cancel a review. - Changing
requiredDecisionsorcountedDecisionTypesdoes not change the status immediately. The new rules are applied, against all existing decisions, the next time a counted decision is submitted.
Common Patterns
| Goal | Configuration |
|---|---|
| Two approvals from the legal team | requiredDecisions: 2, countedDecisionTypes: ["APPROVAL"], approvalGroups: ["legal-reviewers"] |
| Proof that a policy was read | requiredDecisions: 1, countedDecisionTypes: ["ACKNOWLEDGMENT"] |
| Collect comments, then one approver decides | requiredDecisions: 1, countedDecisionTypes: ["APPROVAL"]; reviewers submit COMMENT decisions and the approver submits the APPROVAL |
| Staged sign-off | Submit each stage's final decision with a follow-up review for the next stage |
Permissions
| Operation | Required permission |
|---|---|
| List or read reviews and decisions | READ_DOCUMENTS |
| Create or update a review, submit a decision | WRITE_DOCUMENTS |
See API Permissions.
Troubleshooting
| Problem | Likely cause | What to check |
|---|---|---|
409 Conflict when submitting a decision | The 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 access | The user is not in any of the review's approvalGroups. | Compare the user's groups with the review. |
| A review completed although someone rejected | Completion counts decision records, not outcomes. | Read the decisions and apply your own approval rule. |
| A review never completes | Reviewers are submitting a type that is not in countedDecisionTypes. | Check the review's countedDecisionTypes. |
400 when creating or updating a review | countedDecisionTypes is empty, has duplicates, or contains an unknown type. | Use only the four supported types. |
| Reviewers were not notified | No notifications were supplied, or site notification settings are incomplete. | Check the request and the site's notification configuration. |
API Reference
- Add document review
- Get document reviews
- Get document review
- Update document review
- Add document review decision
- Get document review decisions