API documentation

Prooflane API readiness for verification, fraud, and KYC-adjacent lanes.

Use Prooflane as an API-first sidecar for high-risk marketplace and workflow actions: send an event, receive a hosted verification link, then read a policy decision and audit trail.

Create workspace key Webhook quickstart

Ingest

Your app sends one risky action with a scoped bearer key and stable customer_event_id.

Host

Prooflane returns a single-use verification link that asks only for configured fields and consent.

Decide

The policy engine returns allow, review, or block with reason codes and a risk score.

Audit

Every API action, subject submission, hosted link, and decision is written to audit logs.

Event quickstart

Workspace keys are generated from a Prooflane flow page. The event API accepts the Idempotency-Keyheader for retry discipline and enforces dedupe on customer_event_id.

curl -X POST https://api.prooflane.com/api/v1/events \
  -H "Authorization: Bearer pl_live_or_test_key" \
  -H "Idempotency-Key: seller-listing-123" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_event_id": "seller_listing_123",
    "flow_id": "flow_123",
    "subject": {
      "external_subject_id": "seller_456",
      "type": "human",
      "email": "owner@example.com"
    },
    "trigger": {
      "type": "listing_publish",
      "source": "marketplace_app",
      "risk_context": { "listing_value": 2400 }
    }
  }'

Endpoint surface

Current routes and production contract

OpenAPI 3.1 spec: openapi.yaml

POST /api/v1/events

events:write

Create a verification event, upsert the subject, and return a hosted verification URL.

GET /api/v1/events

events:read

List event status, decisions, and hosted link references for the current lane store.

GET /api/v1/events/{eventId}/decision

decisions:read

Fetch decision outcome, risk score, reason codes, and the deterministic policy trace.

GET /api/v1/audit-logs

audit:read

Read append-only audit events for API intake, hosted links, evidence, and decisions.

Event response

A new event returns the hosted subject URL and an expiration timestamp. Duplicate events return the same event with duplicate set to true.

{
  "id": "vevt_7d2c91a4",
  "status": "awaiting_subject",
  "duplicate": false,
  "hosted_verification_url": "/verify/c26c9bcf2d1d47f486ad09a6b5fd7d6b2a13",
  "customer_event_id": "seller_listing_123",
  "expires_at": "2026-05-31T14:05:00.000Z"
}

Decision response

Decisions are intentionally explainable: every outcome includes reason codes and a policy trace suitable for customer support, manual review, and internal audit.

{
  "event_id": "vevt_7d2c91a4",
  "status": "decided",
  "decision": "review",
  "risk_score": 42,
  "reason_codes": ["proof_link_missing", "high_sensitivity_lane"],
  "policy_trace": {
    "missingFields": [],
    "matchedAllowDomain": "example.com",
    "matchedBlockDomain": null,
    "reasonCodes": ["proof_link_missing", "high_sensitivity_lane"],
    "riskScore": 42
  }
}

Webhooks and signing

Designed for customer callback delivery

Customer callbacks are enabled per workspace. Production callbacks should be signed with HMAC-SHA256 over timestamp.raw_body, include an idempotency key, and retry only until a customer endpoint returns a 2xx status.

Headers: Prooflane-Timestamp, Prooflane-Signature, and Idempotency-Key.

decision.created

{
  "id": "evt_018fb6b7a8",
  "type": "decision.created",
  "created_at": "2026-05-30T14:09:00.000Z",
  "data": {
    "event_id": "vevt_7d2c91a4",
    "customer_event_id": "seller_listing_123",
    "decision": "review",
    "risk_score": 42,
    "reason_codes": ["proof_link_missing"]
  }
}

Policy decisions

Current outcomes are allow, review, and block. The policy engine uses required fields, consent, allowlisted domains, blocklisted domains, proof-link requirements, and sensitivity.

policy_defaultconsent_missingrequired_fields_missingdomain_blocklistedproof_link_missinghigh_sensitivity_lanedomain_allowlisted

Compliance boundary

Prooflane does not provide live KYC, AML, sanctions, liveness, biometric, document verification, credit, banking, or government-ID checks. Regulated provider integrations require vendor contracts, data processing terms, compliance review, jurisdiction review, and explicit production enablement.

Prooflane should be positioned as an API orchestration and policy layer until those provider approvals are in place.