Submissions

The Submissions endpoints expose your organization’s submission register and let an external system record submission events so a regulator portal callback, a customer assurance platform, or an internal delivery service can update a package’s state without going through the UI.

v1 supports reading requirements and packages, plus creating events.

For shared conventions (auth, errors, pagination, ID format, reason field), read v1 conventions first.

Scopes required

Endpoints

List submission requirements

GET /api/v1/governance/submissions/requirements
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "submissionRequirements": [
    {
      "id": "subreq_01HXY...",
      "requirementKey": "quarterly-environmental-discharge",
      "title": "Quarterly environmental discharge report",
      "submissionKind": "regulator_report",
      "status": "active",
      "createdAt": "2026-01-15T08:21:43.000Z",
      "updatedAt": "2026-04-15T08:21:43.000Z"
    }
  ],
  "pagination": {}
}

Get one submission requirement

GET /api/v1/governance/submissions/requirements/:requirementId
Authorization: Bearer <access-token>

Returns the single-requirement shape from the list above.

List submission packages

GET /api/v1/governance/submissions/packages
Authorization: Bearer <access-token>

Query parameters:

Response:

{
  "submissionPackages": [
    {
      "id": "subpkg_01HXY...",
      "submissionRequirementId": "subreq_01HXY...",
      "packageKey": "discharge-report-2026-q2",
      "title": "Q2 2026 environmental discharge report",
      "status": "submitted",
      "dueAt": "2026-07-30T23:59:59.000Z",
      "submittedAt": "2026-07-15T14:08:33.000Z",
      "createdAt": "2026-07-01T08:21:43.000Z",
      "updatedAt": "2026-07-15T14:08:33.000Z"
    }
  ],
  "pagination": {}
}

Get one submission package

GET /api/v1/governance/submissions/packages/:packageId
Authorization: Bearer <access-token>

Returns the single-package shape from the list above.

Record a submission event

POST /api/v1/governance/submissions/packages/:packageId/events
Authorization: Bearer <access-token>
Content-Type: application/json
Idempotency-Key: regulator-portal-callback-2026-07-16-receipt-998877

{
  "eventKind": "receipt_received",
  "occurredAt": "2026-07-16T09:42:33.000Z",
  "eventSnapshot": {
    "recipientReference": "ENV-Q2-2026-998877",
    "ackChannel": "regulator-portal-callback",
    "ackPayload": {
      "status": "received",
      "estimatedReviewBy": "2026-08-15"
    }
  },
  "reason": "Receipt acknowledgement from regulator portal callback for Q2-2026 discharge report."
}

Response: the created event record. The package’s status updates automatically based on the event kind (e.g., a receipt_received event transitions an in-flight package toward accepted, depending on the event policy).

Field notes

Event kinds

The valid eventKind values:

• created - the package was created (usually fired automatically by the system).
• reviewed - the package was reviewed internally.
• approved - the package was approved by an internal authorizer.
• submitted - the package was sent to the recipient.
• receipt_received - the recipient acknowledged receipt.
• rejected - the recipient rejected the package.
• withdrawn - the submitter withdrew the package.
• resubmitted - the package was resubmitted (typically after rejection).
• closed - the package’s lifecycle is closed (terminal).

The product enforces sensible transitions: you can’t record a receipt_received on a draft package, for example. Invalid transitions return 422.

occurredAt

When the event actually occurred (as opposed to when it was recorded). For backdated events (a portal callback that arrived hours after the recipient processed the submission), set this to the true occurrence time. The system records both occurredAt (when it happened) and the record’s own createdAt (when it was logged).

eventSnapshot

A flexible JSON-shaped payload capturing relevant detail (recipient references, acknowledgement payload, delivery channel). Auditors examining the package later see this snapshot. Capture enough to make the event self-explanatory.

reason

Required, like every mutation. Explain the source and intent of the event recording.

Real-case integration: a regulator portal pushes acknowledgement events back

A regulator runs an electronic submission portal. When a company submits a regulatory report through the portal’s UI or API, the portal sends an HTTP callback back to the company’s systems whenever the submission state changes: received, accepted, rejected.

The company integrates the portal callbacks with their Novantra workspace:

1. The company’s webhook receiver accepts the portal’s callback POST.
2. The receiver looks up the corresponding Novantra submission package by the company’s own key (mapped to the portal’s submission identifier in eventSnapshot).
3. The receiver calls POST /api/v1/governance/submissions/packages/:packageId/events with:
   • eventKind mapped from the portal’s notification (received → receipt_received, accepted → closed for accepted state, rejected → rejected).
   • occurredAt from the portal’s timestamp.
   • eventSnapshot capturing the portal’s reference, the company’s internal mapping, and the full callback payload.
   • Idempotency-Key derived from the portal’s delivery ID (so retries don’t double-count).
4. The Novantra package’s status updates automatically.

The service account holds exactly governance.submissions:write for the integration’s purpose. The integration is small (a few dozen lines), runs on the company’s existing webhook stack, and runs only when the portal sends a callback (no polling needed).

Same pattern works for customer-assurance platforms (when a customer marks a security questionnaire response as accepted), procurement portals, and internal delivery services.

Webhooks

The Submissions module emits these webhook events:

• submission.package.status_changed - the package transitioned status.
• submission.package.event_recorded - a new event was recorded on the package.

See Webhooks for the payload shape, signature verification, and delivery semantics.

Related

• Submissions user guide - what the submissions module does and when to reach for it.
• v1 conventions - shared request and response patterns.
• Errors - idempotency keys and retry guidance.
• Webhooks - subscribe to submission events.