POST /documents/Upload response returns a DocNum that doesn't match the actually-persisted document (consistently off by

[SriramChellappan]

We're integrating against the public REST API (https://api.opendental.com/api/v1) and have run into a repeatable issue where the DocNum returned by POST /documents/Upload does not match the DocNum that actually gets persisted in Open Dental. We've reproduced this twice, and both times the real, persisted DocNum was exactly one higher than what the API response reported:

Instance 1

POST /documents/Upload response: DocNum: 514040 (full response also included PatNum, Description, DateCreated, DocCategory, etc. — all otherwise correct/consistent with the upload we sent)
Actual DocNum persisted in Open Dental (confirmed via a direct SQL query against the document table in Open Dental's own Query tool): 514041
514040 does not exist in the document table at all.
Instance 2

POST /documents/Upload response: DocNum: 514095
Actual DocNum persisted (confirmed the same way): 514096
514095 does not exist in the document table.
Both uploads were single, non-duplicated calls — we confirmed via our own server logs that only one POST /documents/Upload request was made in each case, so this isn't a double-submission on our end.

What's more concerning: we also tried re-querying GET /documents?PatNum={PatNum} immediately after the upload to cross-check the DocNum by matching on Description (a value we control and set uniquely on upload). In both cases, that listing endpoint also returned the same wrong DocNum (matching the POST response, not the actual persisted value) — so this isn't limited to the Upload response; a subsequent GET on the same document list reflects the same incorrect number for some period of time afterward.

Additional context that may be relevant:

These calls were made through the public API fallback (no active local eConnector websocket connection at the time), against a live, actively-used practice database — so we suspect this may be a race condition in Open Dental's DocNum/ID allocation under concurrent writes, where the response reflects an ID that gets reserved/echoed slightly ahead of the actual commit, and something else grabs it first. We don't have visibility into the server-side implementation to confirm this.
Questions:

Is this a known issue with POST /documents/Upload (or the public API generally) under concurrent load?
Is there a reliable way to determine the actual DocNum immediately after upload, given that both the create response and an immediate follow-up GET list can report the wrong value?
Is this specific to the public cloud API path, or would it also occur via the eConnector?

[justine]

We're integrating against the public REST API (https://api.opendental.com/api/v1) and have run into a repeatable issue where the DocNum returned by POST /documents/Upload does not match the DocNum that actually gets persisted in Open Dental. We've reproduced this twice, and both times the real, persisted DocNum was exactly one higher than what the API response reported:

Instance 1

POST /documents/Upload response: DocNum: 514040 (full response also included PatNum, Description, DateCreated, DocCategory, etc. — all otherwise correct/consistent with the upload we sent)
Actual DocNum persisted in Open Dental (confirmed via a direct SQL query against the document table in Open Dental's own Query tool): 514041
514040 does not exist in the document table at all.
Instance 2

POST /documents/Upload response: DocNum: 514095
Actual DocNum persisted (confirmed the same way): 514096
514095 does not exist in the document table.
Both uploads were single, non-duplicated calls — we confirmed via our own server logs that only one POST /documents/Upload request was made in each case, so this isn't a double-submission on our end.

What's more concerning: we also tried re-querying GET /documents?PatNum={PatNum} immediately after the upload to cross-check the DocNum by matching on Description (a value we control and set uniquely on upload). In both cases, that listing endpoint also returned the same wrong DocNum (matching the POST response, not the actual persisted value) — so this isn't limited to the Upload response; a subsequent GET on the same document list reflects the same incorrect number for some period of time afterward.

Additional context that may be relevant:

These calls were made through the public API fallback (no active local eConnector websocket connection at the time), against a live, actively-used practice database — so we suspect this may be a race condition in Open Dental's DocNum/ID allocation under concurrent writes, where the response reflects an ID that gets reserved/echoed slightly ahead of the actual commit, and something else grabs it first. We don't have visibility into the server-side implementation to confirm this.
Questions:

Is this a known issue with POST /documents/Upload (or the public API generally) under concurrent load?
Is there a reliable way to determine the actual DocNum immediately after upload, given that both the create response and an immediate follow-up GET list can report the wrong value?
Is this specific to the public cloud API path, or would it also occur via the eConnector?

Hello SriramChellappan,

This is expected behavior for POST /documents/Upload and is specific to that endpoint's rawBase64 implementation. The initial DocNum belongs to a document record containing the rawBase64 data. When the document is later opened in Open Dental, the file is created, a new DocNum is assigned, and the original document record is deleted.

For integrations that need to upload document files, we recommend using POST /documents/UploadSftp instead. That endpoint pulls the file from your SFTP server directly into the customer's document storage and avoids the deferred rawBase64 conversion behavior of POST /documents/Upload.

Thanks!

[SriramChellappan]

Thanks I appreciate your quick response.