Webhook Get Document

Overview

1Flow provides a webhook endpoint that allows you to retrieve document status and extracted data by document ID. This is useful for polling document processing status or retrieving parsed results after upload.

How It Works

When you request document data:

1. Authentication - Request is validated using your webhook secret (if configured)
2. Document Lookup - System retrieves the document by ID (scoped to your organization)
3. Data Retrieval - Returns document status and extracted data (if available)

Webhook URL Format

GET https://app.1flow.io/api/webhook/{webhookId}/document/get?docId={docId}

Where {webhookId} is your unique webhook identifier.

Example:

GET https://app.1flow.io/api/webhook/abc123xyz/document/get?docId=doc_123

API Reference

Endpoint

GET /api/webhook/{webhookId}/document/get

Authentication

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

Authorization: {your-webhook-secret}

Query Parameters

Response Format

Success Response (200):

{
  "success": true,
  "documentId": "doc_abc123xyz",
  "status": {
    "extractionStatus": "INDEXED",
    "docType": "INVOICE",
    ...
  },
  "document": {
    "description": "Invoice from Acme Corp",
    "totalAmount": 1500.00,
    "documentDate": "2025-01-10"
  },
  "extraction": {
    "fields": {
      ...
    },
    "tables": {
      "items": [
        {
          ...
        }
      ]
    }
  }
}

Note:

• The document field contains summary information and will be null if the document has not been extracted yet
• The extraction field contains the full extracted data (fields for header data, tables for line items) and will be null if extraction is not complete
• The schema field is only included when includeSchema=true is specified
• Check status.extractionStatus to see the current state:
  • PENDING - Document uploaded but not yet processed
  • PARTIAL - Document classified but not yet extracted
  • EXTRACTED - Document extracted but not yet indexed
  • INDEXED - Document fully processed and ready

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 parameter

Example Error Response:

{
  "error": "Missing or invalid docId"
}

Code Examples

JavaScript/TypeScript

async function getDocument(
  docId: string,
  webhookId: string,
  secret: string
) {
  const response = await fetch(
    `https://app.1flow.io/api/webhook/${webhookId}/document/get?docId=${docId}`,
    {
      method: 'GET',
      headers: {
        'Authorization': secret,
      },
    }
  );

  const result = await response.json();
  
  if (result.success) {
    console.log('Document status:', result.status.extractionStatus);
    if (result.extraction) {
      console.log('Extracted fields:', result.extraction.fields);
      console.log('Extracted tables:', result.extraction.tables);
    } else {
      console.log('Document not yet extracted');
    }
  }
  
  return result;
}

Python

import requests

def get_document(doc_id, webhook_id, secret):
    url = f"https://app.1flow.io/api/webhook/{webhook_id}/document/get"
    
    params = {
        'docId': doc_id
    }
    
    headers = {
        'Authorization': secret
    }
    
    response = requests.get(url, params=params, headers=headers)
    result = response.json()
    
    if result.get('success'):
        print(f"Document status: {result['status']['extractionStatus']}")
        if result.get('extraction'):
            print(f"Extracted fields: {result['extraction']['fields']}")
            print(f"Extracted tables: {result['extraction']['tables']}")
        else:
            print("Document not yet extracted")
    
    return result

cURL

curl -X GET "https://app.1flow.io/api/webhook/{webhookId}/document/get?docId=your-document-id" \
  -H "Authorization: {your-webhook-secret}"

Best Practices

• Poll for status - Check status.extractionStatus to determine when extraction is complete
• Handle null extraction - The extraction field will be null until extraction completes
• Use HTTPS - Always use HTTPS in production environments
• Store secrets securely - Never commit webhook secrets to version control
• Implement retry logic - Handle transient errors gracefully
• Check extraction errors - Review status.extractionErrors if extraction fails

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

400 Bad Request

• Verify the docId query parameter is included in the URL
• Ensure docId is a valid string

Document Not Extracted

• Check status.extractionStatus to see the current processing state
• Wait for the status to change to INDEXED before expecting document data
• Review status.extractionErrors if extraction has failed

Next Steps

• Learn about webhook uploads for uploading documents
• Explore webhook delete for deleting documents
• Check the Browse App to view your documents in the UI
• Set up webhook callbacks to receive notifications when documents are processed