What document integrations can do
Worthic’s document operations let authorized integrations:
- Upload files for processing and review.
- Store personal reference files without transaction extraction.
- Find accessible documents and download their contents.
- Retrieve processing, extraction, confidence, and recommendation information.
- Update an eligible document’s review details, confirm its filing, or defer review.
REST also provides dedicated endpoints for processing status, password submission, and document-status webhooks.
Document access remains subject to the API client’s workspace, reporting-line, and document permissions.
Operations and permissions
REST paths below are relative to /api/v1.
| Action | REST operation | MCP tool | Required capability |
|---|---|---|---|
| Find documents | GET /documents | list_documents read:documents | |
| Upload a document | POST /documents | upload_document | upload:documents |
| Download a document | GET /documents/{documentId}/download | download_document | download:documents |
| Read extraction and processing information | GET /documents/{documentId}/intelligence | get_document_intelligence | read:document_intelligence |
| Read or act on an eligible document review | POST /documents/{documentId}/review | review_document | review:documents |
| Check processing status | GET /documents/{documentId}/status | get_document_status | read:documents |
| Submit a document password | POST /documents/{documentId}/password | submit_document_password | upload:documents |
| Register or remove a status webhook | POST or DELETE /documents/{documentId}/webhook | No dedicated tool | upload:documents |
| Inspect webhook registration and delivery history | GET /documents/{documentId}/webhook | No dedicated tool | read:documents |
REST accepts the password directly through its protected endpoint. The MCP tool returns a link to Worthic’s password dialog; it does not accept or transmit the password itself.
Permission to upload does not automatically grant permission to download, inspect extraction results, or confirm a review.
Choose an upload mode
The submissionMode determines what Worthic should do with the file.
| Mode | Purpose |
|---|---|
| worthiq_review | Submit the document for analysis and the applicable Inbox review and extraction workflow. |
| user_reference | Store the file in the API client owner’s personal files without automatic transaction analysis. |
Personal reference uploads require the API client to be linked to a human owner. An optional targetFolderPath specifies the destination within that personal filing flow.
Choose the mode deliberately. A receipt intended to support transaction processing has a different purpose from a reference document you only want to retain.
Upload through REST
REST uploads use multipart/form-data, with the file in a field named file.
Optional fields include:
- submissionMode
- sourceEntityId
- sourceAccountId
- notes
- targetFolderPath, for personal reference uploads
Example multipart fields:
POST /api/v1/documents
file: <PDF file>
submissionMode: worthiq_review
sourceAccountId: <account ID>
notes: October bank statement
Supply authentication through the API client’s secure configuration.
Account and reporting-line identifiers must be within the client’s permitted scope. They provide source context; review the resulting destination rather than assuming the file has already been filed correctly.
Uploads are limited to 25 MB per file through this API.
Upload through MCP
Call upload_document with the file name and Base64-encoded file contents:
{
"fileName": "bank-statement-october.pdf",
"mimeType": "application/pdf",
"base64": "<Base64-encoded file contents>",
"submissionMode": "worthiq_review",
"sourceAccountId": "<account ID>",
"notes": "October bank statement"
}
The connected application must supply the actual file contents. A local file path or a filename alone is not an upload.
The same underlying upload-size limit and access checks apply.
File formats and extraction
For transaction extraction, use supported formats such as PDF, CSV, Excel .xlsx, or supported images including JPG, PNG, and WebP.
Extraction depends on the file containing readable, identifiable information. CSV and Excel files should include clear column headers. They do not need to follow one fixed Worthic template.
Storing a file does not guarantee that its format supports transaction extraction. Personal reference uploads do not run the transaction-analysis workflow.
Track processing before reviewing
An accepted upload is not necessarily a completed extraction. Store the returned document id and inspect its processing state.
For REST, request:
GET /api/v1/documents/{documentId}/status
The response includes:
- processingState
- passwordRequired
- reviewEnabled
For MCP, call get_document_status with the document ID to check processingState, passwordRequired, and reviewEnabled. Use get_document_intelligence when you also need extraction results, confidence information, or recommendations.
Allow processing to finish before acting on extraction results. Do not upload the same file again simply because it is still processing.
Find and download documents
Use the document-listing operation to find files within the client’s access scope.
REST supports query parameters such as q, status, documentType, and limit. MCP uses query for the search text, alongside its other supported filters.
Downloading differs between the interfaces:
- REST returns the file contents with the appropriate download headers.
- MCP returns document metadata and Base64-encoded file contents.
A document appearing in a listing does not remove the need for the separate download capability.
Inspect extraction results and recommendations
Use get_document_intelligence, or its REST endpoint, to retrieve available processing, extraction, confidence, review, and recommended-action information.
Review the proposed document type, destination, extracted values, and any reported issues.
Recommendations are not equivalent to completed filing or user approval. A confidence value helps identify what needs checking; it does not guarantee that the interpretation is correct.
Read and update a document review
For eligible API or AI-submitted workspace documents, the review operation supports:
| Operation | Purpose |
|---|---|
| get | Retrieve the current review information. |
| update | Change supported review details. |
| confirm | Execute the reviewed filing and applicable processing actions. |
| review_later | Defer the review. |
This is not a general-purpose editor for every document in the library. Personal reference files do not use this review flow.
Supported review changes include:
- Document type.
- Target type: account or entity.
- Target name.
- Library path.
- Recommended action.
- Whether transactions should be imported.
Retrieve the review first and check its current values before submitting changes.
For example, a REST review request can update the document type:
{
"operation": "update",
"expectedVersion": "<current document updatedAtIso>",
"changes": {
"documentType": "Transaction statement"
}
}
Send it to:
POST /api/v1/documents/{documentId}/review
For MCP, call review_document with the same arguments plus documentId.
Confirm filing and transaction import deliberately
Document confirmation can file the document and execute its applicable recommended actions.
When confirming, explicitly choose whether to import transactions. For example, to confirm filing without transaction import:
{
"operation": "confirm",
"expectedVersion": "<latest document updatedAtIso>",
"changes": {
"importTransactions": false
}
}
Set importTransactions in the confirmation request itself rather than relying on an earlier review screen or request.
This is particularly useful when a statement is supporting evidence and its transactions already arrive through a bank connection.
Document confirmation is separate from reviewing and confirming individual ledger transactions. Check the returned action results to see what was completed.
Handle review conflicts
Document review accepts an optional expectedVersion, based on the document’s current updatedAtIso value. Including it helps prevent an integration from acting on an outdated review.
If another change has occurred, Worthic can return ok: false with stale_review and refreshed review information.
Inspect the operation result, not only the HTTP status. Retrieve or use the refreshed review, check the changes, and retry only when the intended action is still appropriate.
Unlike transaction editing, document review does not use the transaction editor’s opaque version value.
Password-protected documents
A protected document can pause in awaiting_password. Review remains unavailable until the document has been unlocked and processed.
An integration can submit the password securely through:
POST /api/v1/documents/{documentId}/password
Example body:
{
"password": "<document password>",
"save": false
}
Use a secure password-input mechanism. Do not put passwords in filenames, notes, URLs, ordinary assistant messages, or application logs.
Optional password saving requires a human owner associated with the API client.
For MCP, call submit_document_password with the documentId. If a password is required, the tool returns an unlockUrl. Open this link, sign in with permission to edit the document, and enter the password directly in Worthic’s password dialog. The link does not grant access or unlock the document by itself. After submitting the password, call get_document_status to check processing progress.
Do not include a password, password-saving preference, or idempotency key in the MCP call; this tool accepts only documentId. Any password-saving choice is made inside Worthic.
Do not send an Idempotency-Key header with password submissions; this endpoint rejects it.
Receive processing-status webhooks
Instead of repeatedly checking status, the API client that submitted a document can register a webhook:
POST /api/v1/documents/{documentId}/webhook
Provide a public HTTPS callback URL and a signing secret of at least 32 characters:
{
"url": "https://example.com/worthic/document-status",
"secret": "<secure signing secret>"
}
Notifications identify the event, document, workspace, and processing state. The event type is document.processing_status.
Verify the X-Worthic-Signature using HMAC-SHA256 over the timestamp, a period, and the raw request body:
<X-Worthic-Timestamp>.<raw request body>
Use the event ID to recognize repeated deliveries. After receiving a notification, retrieve the document’s current status or intelligence before taking further action.
Use the webhook endpoint’s GET operation to inspect registration and recent delivery history, or DELETE to remove the registration.
Webhook registration is restricted to the submitting API client. Do not supply an Idempotency-Key header when registering the signing secret.
Retries and verification
For supported upload and review operations, use:
- The Idempotency-Key header with REST.
- The idempotencyKey argument with MCP.
Idempotency keys apply only to operations that support them. Do not supply one when submitting a document password or registering a webhook through REST. The MCP submit_document_password tool accepts only documentId and returns a link for entering the password securely in Worthic; it does not submit the password itself.
Reuse the key for an identical retry after an uncertain response. Password submission and webhook registration are exceptions, as described above.
After each operation, check the returned document identifier, processing state, review result, or action results. Avoid assuming that upload acceptance, extraction completion, filing, and transaction confirmation are the same event.
Consult the REST API specification for the operations it documents and their request schemas.