API reference

Endpoints built for risk decisions, not public shaming.

All requests use https://api.frddb.com, bearer authentication, and optional dated versioning with FRDDB-Version.

POST

/check

Returns score, level, confidence, reasons, summary counts, and a recommended action. Requires the lookup scope.

Request body

{
  "email": "buyer@example.com",
  "context": {
    "event": "signup",
    "amount": 4900,
    "currency": "USD"
  }
}

Response body

{
  "risk_score": 72,
  "risk_level": "high",
  "confidence": 0.81,
  "reasons": [
    "multiple_recent_chargeback_reports",
    "trial_abuse_reports",
    "recent_activity"
  ],
  "summary": {
    "report_count": 4,
    "reporting_org_count": 3,
    "first_seen": "2026-01-14T00:00:00Z",
    "last_seen": "2026-05-01T00:00:00Z"
  },
  "recommended_action": "manual_review"
}

POST

/reports

Submits a verified abuse report with category, occurred time, and evidence type. Requires the report scope. Use Idempotency-Key for retries.

Request body

{
  "email": "buyer@example.com",
  "category": "chargeback",
  "occurred_at": "2026-05-04T12:00:00Z",
  "amount": 9900,
  "currency": "USD",
  "evidence_type": "stripe_dispute",
  "external_case_id": "dp_123",
  "notes": "Dispute filed after successful service usage."
}

Response body

{
  "report_id": "rep_123",
  "status": "accepted",
  "subject_reference": "subj_123",
  "will_affect_score": true
}

POST

/outcomes

Attaches outcome feedback to a report. Requires the report scope and ownership of the report.

Request body

{
  "report_id": "rep_123",
  "outcome_type": "dispute_lost",
  "occurred_at": "2026-05-06T12:00:00Z",
  "metadata": {
    "processor": "stripe"
  }
}

Response body

{
  "outcome_id": "out_123",
  "report_id": "rep_123",
  "accepted": true
}

Scopes

lookup can call /check. report can call /reports and /outcomes. admin is reserved for key and org operations.

Idempotency

Write endpoints accept Idempotency-Key. Reusing a key for the same org returns the stored result instead of creating duplicates.

Recommended actions

Expect allow, step_up_verification, manual_review, or block_or_require_prepay.