API and webhooks integration

Droqify is built around asynchronous jobs. This guide describes the integration pattern and the building blocks. Confirm the exact request and response shapes against the API reference for your deployment.

The jobs-first model

Most document operations do not return results immediately. They enqueue work on a queue and return a job identifier. A background worker runs the pipeline and updates the job as it goes.

1. Submit the document (upload, remote upload or reprocess).
2. Receive the document ID and job ID.
3. Poll the job status endpoint, GET /api/v1/jobs/{job_id}/status, or wait for a webhook.
4. When the job completes, fetch the document and its extracted fields.

Design your client to be idempotent and patient. Documents can pause for human review, so a job may sit in a waiting state until a person approves it.

API keys

Administrators create API keys in the portal’s API integration area (the API surface is /api/v1/api-keys). Each key has a name, a set of permissions chosen from the available list, an optional description and an optional expiry. Points to know:

• The full key value is shown once, at creation. Store it in a secret manager.
• Only a short prefix is shown afterwards for identification.
• Grant the minimum permissions the integration needs.
• Revoke a key if it may be exposed.
• Keys are sent in an X-API-Key header on the remote upload API.
• At present API keys are not available to tenant accounts on the shared host; Private and Enterprise deployments are the route for key-based remote upload.

Webhooks

Instead of polling, register a webhook configuration with a target URL, the events you want and, optionally, a signing secret. Available events cover the document lifecycle: text extracted, classified, fields extracted, summarized, completed and failed, plus claim summary events. The API lists the valid events. You can send a test delivery to a configuration and review recent deliveries to debug your receiver.

Receiver guidelines:

• Respond quickly with a success code and do the heavy work afterwards.
• Verify the signature if you set a signing secret.
• Treat deliveries as at-least-once and de-duplicate on the document and job IDs.
• Keep polling as a fallback for missed deliveries.

Remote upload

External systems can push documents through the remote API, with a document file and JSON metadata. It returns a document ID and a job ID, and there are endpoints to check status and fetch results. Metadata can include a predefined classification, custom fields and index values. See the guide on bulk and remote upload.

Errors and limits

Expect standard HTTP status codes. The API applies rate limiting, so back off and retry if you receive a rate-limit response. Supported formats on remote upload are PDF, DOCX, DOC, PNG, JPG, JPEG and TIFF.