Public API - Document Submission and Locking

User Personas: Admin | Project Manager

When your organization uses the Public API to connect eSUB Fusion to an external system, your project documents gain a small set of integration behaviors: a Submit action, integration status chips, optional locking, and an unlock path for exceptions. This article shows what each of those looks like in the UI and how the behavior differs between documents.

These features only appear when the API module is enabled for your organization. If you do not use the Public API, your documents are not affected by anything described here.

You will need the appropriate Integrations - API permissions to submit or unlock documents. See the Permissions table at the end of this article.

Use the links below to jump to a topic:

• Before You Start: How This Behavior Is Configured
• Submitting a Document
  • Where the Submit Action Appears
  • The Submit Confirmation Dialog
• Tracking Integration Status
  • Integration Status Chips
  • Lock Icons in the Log
  • Buttons on the Document View
• Purchase Order Behavior
• Change Order Request Behavior
• Integration Errors and the Error Log
• Unlocking and Re-Submitting
• Revising a Locked Document
• Permissions
• FAQ

Before You Start: How This Behavior Is Configured

Everything in this article is driven by two settings your Admin configures per document type under Settings > Integrations > API: Manual Submit for Integration Pickup and Lock on Submit for Integration Pickup. Those settings, and the rest of the API setup, are covered in Public API - Getting Started.

The short version:

• When Manual Submit is Enabled, a document must be submitted by a user before the integration can pick it up. Everything in this article assumes this setting.
• When Manual Submit is Disabled, documents are available to the integration as they change, the Submit flow is hidden, and no locking applies.
• Lock on Submit controls how much of the document becomes read-only once submitted: No Lock, Partial Lock, or Full Lock. What each level locks differs by document type; see the Purchase Order and Change Order Request sections.

Locking is enforced both in eSUB Fusion and on the server. An integration or API call that tries to change a locked document is rejected, so the lock you see on screen is the same lock the external system sees.

Submitting a Document

A document becomes eligible for Submit when two things are true: it has reached a qualifying status for its document type, and you hold the Submit permission. Qualifying statuses are listed in the behavior sections below.

Where the Submit Action Appears

Once a document is eligible, Submit appears in two places:

• On the log, in the row's three-dot menu.
• On the document view, as a button in the header.

The Submit Confirmation Dialog

Selecting Submit opens a Submit for Integration Pickup dialog explaining that the document will be marked as ready for the configured integration. The dialog adapts to your organization's Lock on Submit setting for that document type:

• With No Lock, the confirmation button reads Submit and no warning is shown.
• With Partial Lock or Full Lock, a warning banner states what will be locked and the confirmation button reads Submit and Lock.

On confirmation, eSUB flags the document as ready for pickup and applies the configured lock.

Tracking Integration Status

After a document is submitted, its integration state is visible without opening the document. The Integration column appears on the project logs and on the Global logs for each supported document type.

Integration Status Chips

Chip	What it means	What the hover shows
	The document is flagged and waiting for your integration to pick it up.	When it was submitted and by whom.
	the document was submitted but has since been unlocked; it keeps its submission history but is not awaiting pickup until it is re-submitted.	A timeline: submitted when and by whom, when the integration initially acknowledged it, and that it is available for resubmission (after being unlocked in eSUB).
	Your integration has picked up the document and confirmed it through the acknowledgement API.	A timeline: submitted when and by whom, and when the integration acknowledged it.
	Your integration reported a problem with the document.	The message your integration sent back. See Integration Errors.
	Your integration reported non-blocking information about the document. The handoff did not fail and nothing is locked out; review the message and address it at your convenience.	The message your integration sent back. See Integration Errors.

The same chips also appear on the document itself, in the view and edit headers, so you always know a document's integration state while working in it.

Lock Icons in the Log

Lock state is shown by an icon in the first column of the log, next to the document number. Hovering the icon explains the state.

Icon	What it means
	The document is locked and read-only while submitted for integration pickup (Full Lock, or a lock from the document's own status such as Revised).
	The document is partially locked. Some sections are read-only; see the per-document sections below for exactly what stays editable.
	The document was unlocked by an Admin. Hovering shows when it was unlocked and by whom. See Unlocking and Re-Submitting.

Buttons on the Document View

The document view header carries the integration action buttons. Which one you see depends on the document's current state and your permissions.

Button	When it appears
	The document is eligible and you hold the Submit permission. Selecting it opens the confirmation dialog.
	The document has been submitted and is awaiting pickup. The button is disabled; it is a status, not an action.
	The integration has acknowledged pickup. Also disabled; the hover shows the acknowledgement timeline.
	The integration reported an error, or the document was unlocked. Selecting it runs the same flow as Submit and overwrites the previous submission details.
	The document is locked and you hold the Unlock permission. See Unlocking and Re-Submitting.

Purchase Order Behavior

A Purchase Order can be submitted once it reaches the Open, Partial Shipment, Received in Full, or Complete status. 

Because POs often continue receiving shipments after they are sent to an accounting system, the lock levels are designed around keeping Receiving usable:

Lock level	What it means on a Purchase Order
No Lock	The PO stays fully editable everywhere.
Partial Lock	General Info becomes read-only except: Notes, Status (you cannot move it back to Draft or Pending) Attachments, and specific date fields.  PO Lines are locked. Receiving remains fully functional, so you can keep logging shipments against the submitted PO.
Full Lock	Nothing is editable, including: Status PO Lines Receiving.  Choose this only if the PO will not need to track further shipments; otherwise use a revision for changes.

A submitted PO shows its state in the view and edit headers as chips next to the document title, and the disabled status button in the header confirms it.

Change Order Request Behavior

A Change Order Request can be submitted once it reaches the Approved status. 

On a COR, locking centers on the pricing content:

Lock level	What it means on a Change Order Request
No Lock	The COR stays fully editable everywhere.
Partial Lock	General Info becomes read-only except: Notes  Status (you cannot move it back to a Potential or Pending group status) Attachments Date Sent Respond By Returned On Date Approved The Worksheet and Summary are locked.
Full Lock	Nothing is editable, including: Status Worksheet Summary Track any further changes with a revision.

A document can also be locked for reasons unrelated to the API. A PO or COR in the Revised status is locked on its own account. If you see a lock you cannot explain, check the document's status before checking the API settings.

Integration Errors and the Error Log

After pickup, your integration reports back through the acknowledgement API: either a confirmation that the document was processed, or a problem. Problems come in two types:

• An Error means the handoff failed and needs attention.
• An Issue is non-blocking information from your integration.

A document in an error state is flagged everywhere you would look for it: the log's Integration column shows an Error chip whose hover contains the message your integration sent, and the document's own header shows an Integration Error chip with the same hover.

Errors and issues from every document also collect in one place: the Error Log tab under Settings > Integrations > API. The log is searchable and filterable, shows the document each entry belongs to with a link, and covers Purchase Orders and Change Order Requests.

eSUB does not detect integration errors on its own. The Error and Issue indicators and the Error Log only show through the acknowledgement API. If a document is never acknowledged, nothing surfaces for it.

Unlocking and Re-Submitting

Unlocking exists for one situation: a document was submitted incorrectly and needs changes in both eSUB and your external system. It is an exception path, not part of the normal workflow.

Admins with the Unlock permission can unlock a locked document from the Unlock button on the document view or from the log's three-dot menu. Either route opens a confirmation dialog that:

• Re-checks the document's live integration status.
• Warns you, with a timestamp, if the integration already confirmed processing the document, because changes already integrated into your systems will not be undone by unlocking.
• Requires a confirmation checkbox before the Unlock button enables.

Once unlocked, the document is fully editable again and keeps a visible record that it went through the integration: the log shows the unlocked icon, and hovering it shows when the document was unlocked and by whom.

An unlocked document can be re-submitted from the Resubmit button or the log's 3-dot menu. Re-submission follows the same process as the original submission, and the document re-locks per your organization's settings.

Re-submitting overwrites the previous submission details. The original submitted timestamp and submitting user are replaced by the new submission's. If your team relies on submission history for audit purposes, record the original details before re-submitting.

If your team unlocks documents regularly, the real problem is usually the Lock on Submit configuration or the approval workflow feeding it. For routine changes to a submitted document, a revision is the better path.

Revising a Locked Document

A locked document is not a dead end. You can create a revision (R1, R2, and so on) at any time. The revision is a new, fully editable document with its own status workflow, and it can be submitted for integration pickup on its own once it qualifies. eSUB keeps the original and every revision as separate records, so the integration history of the original submission is preserved.

See the Purchase Orders and Change Order Requests articles for how revisions work in each log.

Permissions

The behaviors in this article are controlled by the Integrations - API permission section, which appears only when your organization has the API module enabled.

For the full permissions table covering credentials and settings, see Public API - Getting Started.

FAQ

Why do I not see the Submit button on my document?

Check four things: your organization has the API module enabled, Manual Submit is Enabled for that document type in the API Settings, the document has reached a qualifying status, and you hold the Submit permission.

Why can I not edit my document after submitting it?

Your organization's Lock on Submit setting locked it. See the Purchase Order or Change Order Request section for exactly what stays editable at each lock level. An Admin with the Unlock permission can unlock it, or you can create a revision.

Can I undo a submission?

There is no undo. An Admin can unlock the document, which makes it editable again and lets it be re-submitted. If the integration already picked it up, correct the data in both systems.

Does re-submitting keep the original submission details?

No. Re-submission overwrites the previous submitted timestamp and submitting user. Record the original details first if you need them for audit purposes.

My document is locked but was never submitted. Why?

Status locks are separate from API locks. A PO or COR in the Revised status is read-only regardless of the API settings. Check the document's status first.

Which documents support Submit and Lock today?

Purchase Orders and Change Order Requests. eSUB is actively expanding the Public API, and additional document types will be added to this article as they ship. For current API capabilities, see the eSUB Public API Reference.

What is the difference between an Error and an Issue?

An Error means the handoff failed and needs correction and re-submission; an Issue is non-blocking information logged for your review, and the document's integration state is unaffected. Both appear in the Error Log with the message your integration sent.