Delete API

PreviousNext

Permanently delete documents and all extracted data via the Doc-Vision REST API

Overview

DocVision provides a webhook endpoint that allows you to permanently delete documents and all associated data. This operation is irreversible and removes the document, extracted data, search index entries, reconciliation links, and associated files.

How It Works

When you delete a document:

  1. Authentication - Request is validated using your webhook secret (if configured)
  2. Document Lookup - System finds the document by ID (scoped to your organization)
  3. Hard Delete - Permanently removes the document, extracted data, search index entries, reconciliation links, and associated files

Webhook URL Format

POST https://app.doc-vision.com/api/webhook/{webhookId}/document/delete

Where {webhookId} is your unique webhook identifier.

Example:

POST https://app.doc-vision.com/api/webhook/abc123xyz/document/delete

API Reference

Endpoint

POST /api/webhook/{webhookId}/document/delete

Authentication

If a webhook secret is configured, include it in the Authorization header:

Authorization: {your-webhook-secret}

Request Body

Send a JSON body with the document ID:

{
  "docId": "your-document-id"
}
FieldTypeRequiredDescription
docIdStringYesThe document ID to delete

Response Format

Success Response (200):

{
  "success": true,
  "message": "Document deleted successfully",
  "documentId": "doc_abc123xyz"
}

Error Responses:

  • 401 Unauthorized - Invalid or missing webhook secret
  • 404 Not Found - Invalid webhook ID or document not found
  • 400 Bad Request - Missing or invalid docId in request body

Example Error Response:

{
  "error": "Missing or invalid docId in request body"
}

Code Examples

JavaScript/TypeScript

async function deleteDocument(
  docId: string,
  webhookId: string,
  secret: string
) {
  const response = await fetch(
    `https://app.doc-vision.com/api/webhook/${webhookId}/document/delete`,
    {
      method: 'POST',
      headers: {
        'Authorization': secret,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        docId: docId,
      }),
    }
  );

  const result = await response.json();
  
  if (result.success) {
    console.log(`Document ${result.documentId} deleted successfully`);
  } else {
    console.error('Delete failed:', result.error);
  }
  
  return result;
}

Python

import requests

def delete_document(doc_id, webhook_id, secret):
    url = f"https://app.doc-vision.com/api/webhook/{webhook_id}/document/delete"
    
    payload = {
        'docId': doc_id
    }
    
    headers = {
        'Authorization': secret,
        'Content-Type': 'application/json'
    }
    
    response = requests.post(url, json=payload, headers=headers)
    result = response.json()
    
    if result.get('success'):
        print(f"Document {result['documentId']} deleted successfully")
    else:
        print(f"Delete failed: {result.get('error')}")
    
    return result

cURL

curl -X POST https://app.doc-vision.com/api/webhook/{webhookId}/document/delete \
  -H "Authorization: {your-webhook-secret}" \
  -H "Content-Type: application/json" \
  -d '{
    "docId": "your-document-id"
  }'

Best Practices

  • Verify before deleting - Double-check the document ID before deletion
  • Use HTTPS - Always use HTTPS in production environments
  • Store secrets securely - Never commit webhook secrets to version control
  • Handle errors gracefully - Implement proper error handling for failed deletions
  • Confirm deletion - Verify the success response before considering the operation complete

Troubleshooting

401 Unauthorized

  • Verify your webhook secret matches the one in Organization Settings
  • Ensure the Authorization header is included in the request
  • Check that the secret doesn't have extra spaces or characters

404 Not Found

  • Verify the webhook ID in your URL matches the one in Organization Settings
  • Ensure the document ID is correct
  • Check that the document belongs to your organization
  • The document may have already been deleted

400 Bad Request

  • Verify the docId field is included in the request body
  • Ensure docId is a valid string
  • Check that the JSON body is properly formatted

Frequently Asked Questions

Can I recover a deleted document?

No. The delete operation is permanent and irreversible. All associated data - including extracted fields, search index entries, reconciliation links, and stored files - are removed immediately. Always verify the document ID before deleting.

What happens to webhook callbacks for deleted documents?

If a document is deleted while still being processed, any pending webhook callbacks for that document will not be sent. If the document was already processed, existing callback data in your systems is unaffected.

Can I delete multiple documents at once?

Currently, the API supports deleting one document per request. For bulk deletions, make multiple API calls with different docId values. Consider implementing rate limiting in your client to avoid overwhelming the endpoint.

Is deletion audited?

The deletion removes all traces of the document from the system. If you need an audit trail, we recommend logging the documentId and deletion timestamp in your own system before calling the delete endpoint.

Next Steps