Process File Async

POST
ASYNC
/api/v1/document/{extractionSchemaId}/process-file-async/{fileId}

Queue document processing jobs asynchronously for better scalability and reliable handling of large files. Jobs are processed in the background, and you can poll for results or receive webhook notifications when complete.

Request Parameters

Path Parameters
required
extractionSchemaIdstring

The unique identifier of the extraction schema to use for processing.

required
fileIdstring

The file ID returned from the get-url endpoint after uploading your file.

Headers
required
Authorizationstring

Bearer token for authentication.

required
Content-Typestring

Must be set to application/json

Request Body

Send an empty JSON object {} as the request body.

queue-async-job.js

Responses

Success Response (200) - Job Queued

Job successfully queued for processing. Use the returned jobId to track progress.

job-queued-response.json
Conflict Response (409) - Job Already In Progress

A processing job is already in progress for this file. Duplicate submissions are prevented.

duplicate-job-response.json
Error Responses

Common error responses you might encounter.

async-error-responses.json

Polling for Results

After queuing a job, use the get-file-data endpoint to poll for completion status and retrieve results.

Polling Pattern
polling-pattern.js
⚠️ Polling Best Practices
  • • Use reasonable polling intervals (5-10 seconds) to avoid overwhelming the API
  • • Implement timeout logic to prevent infinite polling loops
  • • Handle network errors gracefully with retry logic
  • • Consider using webhooks for real-time notifications instead of polling
  • • Log polling attempts for debugging and monitoring purposes

Status Response Types

PROCESSING Status

Job is currently being processed. Continue polling until status changes.

processing-status.json
COMPLETED Status

Processing completed successfully. Returns the extracted data along with status information.

completed-status.json
FAILED Status

Processing failed due to an error. Check the error message for details.

failed-status.json

Complete Workflow Example

Here's a complete example showing the full async processing workflow from job submission to result retrieval.

complete-async-workflow.js

Best Practices

Error Handling
  • • Always check for 409 Conflict responses (duplicate jobs)
  • • Implement exponential backoff for failed polling attempts
  • • Set reasonable timeouts to prevent infinite polling
  • • Log job IDs for debugging and support purposes
Performance
  • • Use 5-10 second polling intervals to balance responsiveness and load
  • • Consider webhooks for real-time notifications
  • • Process multiple files concurrently for batch operations
  • • Cache successful results to avoid reprocessing
Monitoring
  • • Track job success rates and processing times
  • • Monitor queue depths during high-volume periods
  • • Set up alerts for failed jobs or unusual processing delays
  • • Log all API interactions for audit trails
Integration
  • • Use async processing for all files larger than 10MB
  • • Combine with webhooks for event-driven architectures
  • • Store job IDs in your database for tracking
  • • Implement retry logic for transient failures