How It Works

Async by design.
API by default.

PolDex has no dashboard. Submission, monitoring, delivery, key rotation, and credit visibility are all exposed through APIs, webhooks, and email notifications.

Initialize API Access →API Reference
⏳

Async, not synchronous

PolDex returns 202 Accepted immediately. Results arrive via webhook or polling. There is no blocking response with content.

⌘

API is the control surface

Every operation — submission, monitoring, key rotation, credit top-up — happens through the API. No dashboard exists.

◎

Webhook or polling

Results are pushed to your endpoint via signed HMAC-SHA256 webhook, or pulled with GET /v1/jobs/{id}. Your choice.

Full Lifecycle

Step-by-step flow.

01

Submit a document

POST /v1/extract with a document URL or S3 reference. Include your API key in the Authorization header and an Idempotency-Key for safe retries.

POST /v1/extract
Authorization: Bearer pd_live_...
Idempotency-Key: ik_2024_abc123
Content-Type: application/json

{
  "document_url": "s3://your-bucket/policy.pdf",
  "schema": "commercial_gl",
  "webhook_url": "https://your.app/hook"
}
02

202 Accepted — job queued

PolDex acknowledges the request immediately. You receive a job_id and a poll URL. Credits are held against your balance, not captured. Processing begins asynchronously.

HTTP 202 Accepted

{
  "job_id": "job_01hx4mz9p3kqa8",
  "status": "queued",
  "credits_held": 12,
  "poll_url": "https://api.poldex.io/v1/jobs/job_01hx4mz9p3kqa8",
  "estimated_seconds": 45
}
03

Document retrieval

Workers retrieve the document from the provided URL or S3 reference. Streamed to disk — not loaded into RAM. Safe for large multi-page or multi-document submissions.

# Internal — no action required
# Documents streamed to temporary worker disk
# Never held in application memory
# Deleted after extraction completes
04

Schema-constrained extraction

Segmented document content is passed to the extraction layer with schema-constrained prompts. Output is validated against the target schema before being written to the job store. No raw content enters application logs.

# Schema-constrained extraction
# Output: structured JSON against target schema
# Schema validated before write
# No training opt-in by default
05

Truth resolution

Extracted candidate facts are adjudicated. Endorsements are resolved against base policies by effective date. Conflicts are surfaced explicitly as first-class objects.

{
  "facts": [
    {
      "field": "additional_insured",
      "value": true,
      "status": "active",
      "evidence": [{ "page": 3, "citation": "CG 20 10" }]
    }
  ],
  "conflicts": [
    {
      "field": "aggregate_limit",
      "base_value": 1000000,
      "endorsement_value": 2000000,
      "resolution": "endorsement_supersedes"
    }
  ]
}
06

Delivery and settlement

Results are delivered via signed HMAC-SHA256 webhook or available for polling at GET /v1/jobs/{id}. Credits captured on success, released on internal failure.

# Webhook delivery
POST https://your.app/hook
X-PolDex-Signature: t=1745280000,v1=abc123...
Content-Type: application/json

# Polling
GET /v1/jobs/job_01hx4mz9p3kqa8
→ { "status": "complete", "result": {...} }

# Credit settlement
credits_captured: 12
remaining_balance: 988
Delivery Modes

Webhook or polling. Your choice.

Webhook delivery

PolDex POSTs a signed payload to your endpoint when the job completes. Signed with HMAC-SHA256. Retried with exponential backoff on failure. Undeliverable jobs move to DLQ after maximum retries.

Webhook payload
POST https://your.app/webhook
X-PolDex-Signature: t=1745280000,v1=...
X-PolDex-Job-Id: job_01hx4mz9

{ "status": "complete", "result": {...} }

Polling

Poll GET /v1/jobs/{id} at your preferred interval. The response includes the current status (queued, processing, complete, failed) and the full result once complete.

Poll request
GET /v1/jobs/job_01hx4mz9
Authorization: Bearer pd_live_...

→ { "status": "complete",
    "result": { ... },
    "credits_captured": 12 }
Failure Behavior

Failures are bounded and explicit.

Extraction failure

If extraction fails due to an internal error, credits are released. You are not charged for PolDex errors. The job moves to failed state with an error code.

Webhook retry

Delivery failures trigger exponential backoff. After maximum retries, the job is placed in the DLQ. You can retrieve DLQ jobs via API.

402 enforcement

Insufficient credits at submission time return 402 Payment Required immediately. No job is created. No partial work is done.

Ready to integrate?

Self-serve access in minutes. No meeting required.

Initialize API Access →Read the Docs