/apiv2/webhooks/doc

The /apiv2/webhooks/doc API endpoint allows developers to create new documents programmatically in Docwize. It can be used to register metadata, attach files, and optionally start workflows.

Who this is for

Developers integrating external systems with Docwize via a Bearer token. This is a code-level reference, not a portal UI feature.

Overview

Endpoint: POST /apiv2/webhooks/doc

The /apiv2/webhooks/doc endpoint is designed to:

• Register a new document record in the system.
• Upload a document file immediately or obtain an upload URL for later use.
• Optionally link workflows or custom fields during creation.

Authentication

All requests must include a valid Bearer token.

Authorization: Bearer <ACCESS_TOKEN>

Tokens are verified against the issuing company and must be active and not revoked.

Request Format

Method: POST

Content Type: multipart/form-data

Form Fields

Field	Type	Required	Description
payload	JSON string	✅	Contains all metadata and options for the document.
file	Binary	❌	Optional file to upload immediately.

Payload Structure

Example:

{
  "document": {
    "DocumentDetails": {
      "Description": "Monthly Financial Report",
      "Date": "2025-01-31T00:00:00",
      "Reference_Number": "INV-2025-001"
    },
    "FolderIds": ["Finance->Reports->2025"],
    "CCs": ["finance-team@example.com"],
    "deduplicate": true
  },
  "file_extension": ".pdf",
  "workflow": {
    "PortalWorkflowTemplateID": 42,
    "Subject": "Approve Financial Report"
  },
  "user_id": 12
}

Key Fields

DocumentDetails

Core document properties such as:

• Description — The document name or title.
• Date — The date associated with the document.
• Reference_Number — Any unique external or internal identifier.

FolderIds

List of destination folder paths in Docwize (e.g., Projects->Alpha->Design).

deduplicate

Prevents duplicate document creation when a document with the same description already exists in the specified folder.

workflow

(Optional) Starts a workflow immediately after document creation.

File Handling

Files can be uploaded immediately or a pre-signed upload link can be requested for later use.

Option 1 — Immediate Upload

Send the file directly with the request:

curl -X POST https://portal.docwize.com/apiv2/webhooks/doc \
  -H "Authorization: Bearer <TOKEN>" \
  -F 'payload={"document": {...}}' \
  -F 'file=@document.pdf'

Response:

{"document_id": 1201}

Option 2 — Deferred Upload

If the file is omitted, the endpoint returns a pre-signed upload URL:

{
  "document_id": 1202,
  "upload_url": "https://s3.amazonaws.com/...",
  "image_name": "1202_report.pdf"
}

The file can be uploaded using a standard HTTP PUT request:

curl -X PUT "<upload_url>" --upload-file ./document.pdf

Once the file has been uploaded, call:

POST /doc/upload-complete/{doc_id}/{image_name}

This confirms that the upload is complete and finalizes the document.

/apiv2/webhooks/doc/upload-complete/{doc_id}/{image_name}

Purpose: Finalize the document after uploading via a pre-signed URL.

Request Example

POST /apiv2/webhooks/doc/upload-complete/1202/1202_report.pdf
Authorization: Bearer <TOKEN>

Response

{"status": "success"}

Minimal Code Examples

Python (using requests)

import requests

url = "https://portal.docwize.com/apiv2/webhooks/doc"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
payload = {"document": {"DocumentDetails": {"Description": "Test Doc"}, "FolderIds": ["General"]}, "file_extension": ".pdf"}
files = {"payload": (None, str(payload)), "file": open("document.pdf", "rb")}
r = requests.post(url, headers=headers, files=files)
print(r.text)

C# (using HttpClient)

using System.Net.Http;
using System.Net.Http.Headers;

var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_TOKEN");
var form = new MultipartFormDataContent();
form.Add(new StringContent("{\"document\":{\"DocumentDetails\":{\"Description\":\"Test Doc\"},\"FolderIds\":[\"General\"]}}"), "payload");
form.Add(new ByteArrayContent(System.IO.File.ReadAllBytes("document.pdf")), "file", "document.pdf");
var response = await client.PostAsync("https://portal.docwize.com/apiv2/webhooks/doc", form);
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);

Troubleshooting

Issue	Detail
200 OK	Document created successfully.
400	Invalid input or token.
401	Missing or invalid authorization — check the Authorization: Bearer header.
500	Unexpected server error.
Invalid token error ({"error": "invalid token"})	The Bearer token is missing, expired, or revoked. Confirm the token is active and issued for the correct company.
Duplicate document response ("Document already exists, no new document created.")	deduplicate is true and a document with the same description already exists in the target folder. This is expected behaviour, not a failure — the response still includes the existing document_id.

Summary of Flow

Step	Action	Endpoint
1	Create document and metadata	POST /apiv2/webhooks/doc
2	(If deferred) Upload file to returned URL	PUT <upload_url>
3	Confirm upload completion	POST /apiv2/webhooks/doc/upload-complete/{doc_id}/{image_name}

Best Practices

• Always use UTF-8 safe text for descriptions and folder names.
• Use consistent identifiers in Reference_Number for tracking.
• Use deduplicate to avoid redundant entries.
• Handle retry logic for temporary network issues.

Related configuration

• Access Control — the folder structure referenced in FolderIds
• Workflows — workflow templates that can be started via the workflow payload field