Skip to main content

Notifications and Reminders

Notifications deliver information about documents to people. Reminders schedule that work relative to a document date. They differ from webhooks, which accept inbound content, and from EventBridge events, which connect services.

Delivery setup​

In Administration → Workspaces → Notifications & integrations, configure the sender and Amazon SES or SMTP provider. For SES, verify the sender and account sending restrictions in the chosen region. For SMTP, configure the host/security settings and reference credentials using AWS Secrets Manager. Do not put credentials in document metadata.

Save the settings before using Send Test Message. The API equivalent is POST /sites/{siteId}/configuration/notification/test with {"to":"reviewer@example.com"}. A successful request accepts the test; confirm actual delivery and check failed processing rather than assuming receipt.

Send a document notification​

Commercial notification capabilities depend on the installed backend. The v1.19.2 API supports EMAIL and IN_APP notifications. Supply notificationType, subject, body, and at least one CC or BCC recipient.

curl -X POST "${HTTP_API_URL}/documents/${DOCUMENT_ID}/notifications?siteId=${SITE_ID}" \
-H "Authorization: ${AUTHORIZATION_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{"notificationType":"EMAIL","cc":["reviewer@example.com"],"subject":"Invoice ready","body":"Please review the invoice in FormKiQ."}'

Use GET /documents/{documentId}/notifications for the document's notification records and GET /userNotifications for notifications associated with the authenticated user's email. Follow next tokens; see pagination.

Record statusMeaning
WAITINGAwaiting an external trigger; not yet eligible for processing.
PENDINGReady for processing.
ACTION_CREATEDA document action has been created. This is not proof that a person read the message.

Records can include the reminder entity identifiers, scheduled date, normalized recipients, and resulting document action. Check that action and the provider's delivery evidence when diagnosing failures.

Schedule reminders​

Open Orchestration → Document lifecycle → Reminders. Choose the date-source attribute, offset, optional repeat interval, delivery type, recipients, and message. The date-source attribute cannot be changed after creation. Associate the reminder policy with the intended documents and verify an upcoming occurrence using fictional data.

A document must have a valid date for the policy to schedule useful work. The backend scheduler must be running and the delivery provider configured. Review missing values, dates already passed, time zones, and duplicate recipient addresses before activation. Contract Management has its own expiry-reminder configuration.

Event notification policies in FormKiQ Web​

The Notifications lifecycle tab controls supported checkout, legal hold, and agreement-review email behavior. In Web v4.3.8 these policies are applied to actions completed in the web application. Making the same change directly through the API does not run the browser's email policy. Use a separately implemented event consumer if all clients must trigger a common delivery process.

In-app visibility and email delivery do not replace authorization. Links must lead to an authenticated view that checks the recipient's access. Include the minimum document information appropriate for email; CC recipients see other CC addresses.

Troubleshooting​

SymptomCheck
Test accepted but no emailSender verification, SES sandbox restrictions, SMTP secret and TLS configuration, action failures, and provider delivery logs.
Reminder not scheduledPolicy assignment, date-source value, scheduler health, and effective schedule.
No email after an API updateWeb policies do not execute for direct API changes.
Notifications appear emptyCorrect site, authenticated email, pagination, and API permissions.

API: add document notification · Get document notifications · Get user notifications.