Sandbox-first API

API docs

Read the backend OpenAPI contract through Redoc, then use the sandbox page for fixture-only key testing.

Fixture data onlyNo real PIIIdempotencyConsent purposeProduction review

Quickstart Use fixture sandbox View changelog

3-call sandbox pattern

curl -X POST https://sandbox.pramaan.online/v1/verify \
  -H "Authorization: Bearer $PRAMAAN_SANDBOX_KEY" \
  -H "Idempotency-Key: demo-fixture-001" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "name": "Sandbox Worker",
      "phone": "+910000000000"
    },
    "purpose": "household_help_verification_demo",
    "checks": ["identity", "address"],
    "fixture": "fixture_green_domestic_help"
  }'

OpenAPI 3.1

The /v1/verify contract is the source of truth.

This page renders the proxied backend spec from /openapi.json. Use production keys only after approval; use /developers/sandbox for fixture keys and test payloads.

Primary endpoint

POST /v1/verify

curl -sS -X POST https://api.pramaan.online/v1/verify \
  -H "Authorization: Bearer $PRAMAAN_PRODUCTION_KEY" \
  -H "Idempotency-Key: verify-001" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "purpose": "household_help_verification",
    "subject": {"name": "Asha Rao", "phone": "+919876543210"},
    "checks": ["identity", "address"],
    "consent": "captured"
  }'

Sandbox and production keys are split.

Sandbox keys belong on fixture payloads at /developers/sandbox. Production keys are issued only after purpose, consent copy, logging, DSR, support, webhook, and rate-limit review.

Redoc

Rendered backend OpenAPI.

The raw JSON remains available at /openapi.json for CI, SDK tooling, and contract review.

Spec source: /openapi.json

SDKs

Runtime availability matrix.

Runtime	Current status	Safe guidance
cURL	Current	Use environment variables and fixture payloads.
Node	Planned	Use fetch examples unless an npm package is confirmed.
Python	Roadmap	Do not claim pip package availability until published.
Go	Roadmap	Do not claim module availability until published.

Webhooks

Signed event handling for shipped webhook surfaces.

Event	Status	Handling guidance
verification.verdict_emitted	Current	Verify HMAC signature, check timestamp, then process idempotently.
badge.issued	Current	Treat badge issue events as at-least-once deliveries and dedupe by event id.
payment.captured	Current	Reconcile payment state before unlocking downstream workflows.
dsr.completed	Roadmap	Use support ticket route until API export is confirmed.

Current

Webhook security guardrail

PRAMAAN webhook delivery uses HMAC verification, replay-window checks, and idempotent processing expectations for shipped event subscriptions.

Errors

Readable failure states.

Problem response example

{
  "type": "https://docs.pramaan.online/errors/consent_required",
  "title": "Consent required",
  "status": 409,
  "detail": "The verification cannot run until explicit consent is captured.",
  "request_id": "req_sandbox_001"
}

Keep sandbox keys and production API keys separate.

Sandbox keys are for fixture payloads only. Production keys are issued only after purpose, consent, logging, DSR, and support routes are reviewed.

Never paste real API keys, Aadhaar, PAN, OTPs, raw documents, or private keys into examples, screenshots, tickets, or chat.

Checklist

Before production.

Purpose string approved
Consent copy reviewed
Callback URL configured
PII-safe logging
DSR route linked
Support escalation owner
Security contact
DPA path for enterprise

Build consent-first verification carefully.

Start in sandbox with fixture data, then move to production only after purpose, consent copy, logging, DSR, and support routes are reviewed.

Open sandbox Read API docs