Introduction
A file-processing integration needs more than a detector score. It needs to know which document was submitted, whether processing actually finished, and whether the requested evidence has arrived. Treating those as one event can leave an editor looking at an incomplete report while the application displays “done.”
This is documentation-based research, not a live API test. We reviewed Copyleaks’ document-submission, detection and webhook documentation. The workflow matrix below is our proposed application design, not a claim that Copyleaks uses these internal states. We have not measured detection accuracy, delivery reliability or production performance. This article may contain affiliate links.
The practical choice is between submitting text to a synchronous interface and coordinating a file-based job. Our synchronous text sandbox guide covers the former. This guide concentrates on the latter: the boundaries between submitting a document, receiving scan notifications, exporting details and making those details usable.
Document Workflow
Copyleaks’ document AI detection guide describes support for formats including PDF, DOCX and TXT. It explains an asynchronous sequence: enable AI detection, submit the file, receive a completed notification and request detailed exports. The guide distinguishes AI detection results from the Crawled Version, the document representation needed to relate results to the submitted content. Export uses its own completionWebhook.
The submit-file reference documents a PUT submission containing base64, filename and properties. The filename needs the appropriate extension. AI detection is enabled through properties.aiGeneratedText.detect; merely submitting a file is not a reason to assume that analysis was requested. Keep the exact configuration associated with the submission.
The webhook overview explains notifications for asynchronous jobs and discusses reliable delivery. The important design consequence is that your receiver is part of the integration, not a decorative callback field. A successful file-submission request does not establish that your receiver, export destinations and report-building process all work.
Use the following application-state matrix to make that distinction explicit. These labels are ours. Map them to your actual integration rather than treating them as provider response values.
| Suggested application state | Evidence to retain | Next permitted action | What remains unknown |
|---|---|---|---|
| Submission prepared | File fingerprint, intended analysis and safe identifier | Submit through the documented interface | Whether the provider accepted the file |
| Submission accepted | The recorded submission response | Await and associate a scan notification | Whether analysis or export is complete |
| Scan notification received | Original payload, arrival time and job association | Check the event and requested analysis | Whether all report artifacts are available |
| Export requested | Export identifier and requested destinations | Track delivery of the requested artifacts | Whether every destination received valid data |
| Artifacts stored | The received artifacts and processing outcome | Assemble a reviewable report | What the detector output means for authorship |
| Editorial review pending | Report, source document and available provenance | Apply your documented review policy | Whether the author’s explanation resolves concerns |
Separate storage from presentation. An export destination may receive data before a user-facing report is usable; parsing or associating the artifact can still fail. Conversely, a visible summary does not mean that a detailed export has been requested. Show the actual stage rather than replacing uncertainty with an empty report or a reassuring zero.
Operational Checklist
Before submission: identify the document and the intention
Choose an identifier that links the outgoing job to a record you control. Store a file fingerprint and the submitted filename together. A renamed extension does not validate the underlying bytes. Your own acceptance policy should handle unsupported or suspicious uploads before any external submission, without claiming that the provider performs those local checks for you.
Record whether AI analysis was enabled and whether the request was in sandbox mode. In the document guide, sandbox results are mock data. They can help exercise an integration, but they are not evidence of a document’s origin. Keep simulated results visibly separate from results received through a live workflow.
Think about retries before writing the happy path. A missing local response is not sufficient evidence that an earlier request never reached the provider. Preserve the original job association, inspect what is known, and follow the current documented retry behavior. Do not make an accidental second submission look like a second independent test.
At the receiver: separate an event from a conclusion
Persist enough of a notification to investigate what arrived and which job it belongs to. Avoid putting the complete submitted manuscript into routine logs. A log suitable for troubleshooting is not necessarily a suitable content archive, and developers should be able to investigate a delivery problem without broadly exposing customer text.
Plan for callbacks that repeat or arrive while another part of your application is still working. Use job association and your own event-processing record to prevent repeated notifications from creating duplicate reports. Follow the provider’s current guidance on acknowledgement and authentication; this checklist is not a substitute for its security documentation.
Treat completed as a processing milestone. The document guide discusses a suspected-ai-text alert in notifications.alerts. Preserve that information when present, but do not convert its absence into a certificate of human authorship. First distinguish “the requested analysis produced no such alert” from “the relevant payload or analysis was never available.”
During export: specify and check the required artifacts
Decide what your report needs before requesting export. If reviewers need highlighted findings alongside the document text, obtaining only one artifact may leave them unable to interpret the other. Track each requested artifact separately, including an explicit failure or pending state. An incomplete export should not silently become an empty, apparently successful report.
For a concrete application scenario, imagine that the AI-result artifact arrives but the document representation has not. The sensible next action is to keep the report pending and investigate the missing delivery. It is not to invent the missing text or publish a detector judgment without its context. This scenario illustrates our suggested process; it is not an observed vendor failure.
At the editorial handoff: keep the author in the workflow
The reviewer needs more than a processing label. Present the relevant document, detector output and any available writing history together. If a writer provides an outline, drafts or revision records, preserve those as separate evidence rather than replacing them with a score. Decide how a disagreement will be handled before applying the workflow to sensitive decisions.
Define who can resolve technical failures and who can make editorial decisions. A developer can establish that an export failed; that does not establish that the author used AI. Keeping those responsibilities separate makes the system easier to troubleshoot and avoids turning a transport problem into an accusation.
Limits
This workflow is not an accuracy evaluation. Document support, a completed job and an exported report describe capabilities and processing steps. None supplies a measured false-positive rate for your audience or certifies who wrote a document. Our advice is to preserve uncertainty and review context, not to create a new detector threshold.
We also do not establish production latency, availability, retention, privacy or pricing terms here. Check the relevant current documentation and account terms before handling sensitive material. A sandbox exercise cannot establish live detection performance, and successful callbacks cannot establish that every downstream part of your own application is sound.
Keep the synchronous text path distinct. A synchronous response can contain more than a summary; it should not be dismissed as a less detailed report merely because it does not require this document-export sequence. Choose the interface for the input and integration requirements, then evaluate its actual response contract.
Final Verdict
Use an explicit document workflow when your integration receives files and must coordinate notifications and exports. The useful improvement is not another “AI percentage” on a dashboard. It is a defensible record of what was requested, what arrived, what is still missing and what requires an editorial decision.
Start with the state matrix, assign an owner to every unresolved stage and make incomplete reports visibly incomplete. Consult the official contracts for transport details. Use the synchronous guide for text-only integrations rather than applying file-submission assumptions to that endpoint.