API & Webhooks

Everything the dashboard does, the REST API does too: submit statements, retrieve full analyses, and receive webhook callbacks the moment processing finishes. One endpoint in, structured JSON out.

API keys

Manage keys under Settings → Integrations → API Keys:

• Keys are prefixed cg_live_… and shown once at creation — store them in your secrets manager.
• Each key shows created and last used timestamps, so stale keys are easy to spot.
• Revoke any key instantly; create as many named keys as you need (one per environment/integration is good practice).
• Rate limits by plan: 60 req/min (StaqCore), 200 req/min (StaqPro), unlimited (StaqScale).

Submitting a statement

Submit via the public API with a callback_url for the webhook. Conceptually:

curl -X POST https://app.clearstaq.com/api/v1/analyses \
  -H "Authorization: Bearer cg_live_YOUR_KEY" \
  -F "[email protected]" \
  -F "callback_url=https://yourapp.com/webhooks/clearstaq" \
  -F "client_ref=deal-4821" \
  -F 'metadata={"loan_id":"LN-999"}' \
  -F "clearstaq_ai_enabled=true"

The endpoint returns 202 Accepted with an analysis id; the full result arrives asynchronously at your callback_url. clearstaq_ai_enabled opts that submission into the ClearStaqAI visual fraud second-pass (defaults to off; the metadata fraud score always runs). Maximum upload size 25 MB, application/pdf only.

Full request parameters, response schemas, and runnable cURL/Node/Python examples live in the API Reference.

Webhook events

Every API-submitted statement triggers exactly one of two events at your callback_url:

Signature verification

Payloads are signed with HMAC-SHA256 using your API key secret. Verify the signature header on every delivery before trusting the payload:

import hmac, hashlib

def verify(payload_bytes, signature_header, api_secret):
    expected = hmac.new(api_secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Delivery monitoring

Settings → Integrations → Webhook Deliveries logs every outbound webhook attempt for API-submitted statements — your first stop when a callback "didn't arrive." (If the log shows a delivery and your endpoint has nothing, the problem is on the receiving side.)

Retrieving results without webhooks

Poll the analysis by ID, or pull any analysis as JSON from the dashboard: every document's Raw Output tab offers four views — Full Response, Transactions Only, Fraud Report, Income Summary — with one-click Copy and Download JSON. The Raw Output of a real document is the best living reference for payload shapes while you build.

Coming soon

The Integrations page lists an API Sandbox (test without consuming credits) and an Events stream as upcoming — watch the changelog.

---

FAQ

Does an API-submitted statement cost the same? Yes — 1 credit per analyzed document, identical to web upload.

How fast is the webhook after submission? Analysis completes in under 5 seconds for most statements (~15s with visual fraud analysis), and the webhook fires immediately after.

What happens if my endpoint is down? The attempt is recorded in Webhook Deliveries. Build your endpoint to return 2xx quickly (enqueue, then process) and use the analysis ID to fetch anything you missed.

Can I tell which key made which calls? Each key tracks last-used; use one key per integration for clean attribution and painless rotation.

Is there a sandbox? Listed as coming soon. Until then, test with real statements on a trial workspace or use Raw Output JSON from existing analyses as fixtures.