Dashboard

Reporting API Reference

Last Updated: January 5, 2026
API Version: 2.1.0
Feature Flag: REPORTING_ENABLED

The Reporting API provides programmatic access to verification analytics, usage metrics, and compliance data. Use these endpoints to build custom dashboards, automate reporting workflows, or integrate analytics into your applications.

Table of Contents

Overview

The Reporting API is divided into two versions:

Version Purpose Plan Requirements
V1 Core analytics (volume, usage, performance) All plans (with limits)
V2.1 Enterprise-ready analytics with compliance scoring, risk analysis, and credits intelligence All plans (advanced features role-gated)

Key Features:

Authentication

All Reporting API endpoints require an authenticated session. Users must be logged in to their VerifyHuman dashboard to access these endpoints.

Note: These are session-authenticated endpoints, not API key authenticated. For programmatic access, use the dashboard or export functionality.

Common Parameters

All reporting endpoints accept these query parameters:

Parameter Type Required Description
env String Yes Environment: test or live
from String Yes Start date in YYYY-MM-DD format
to String Yes End date in YYYY-MM-DD format
granularity String No Time granularity: day, week, or month (default: day)
limit Integer No Max items in breakdown (plan-limited)
page Integer No Page number for pagination (default: 1)
per_page Integer No Items per page (default: 10, max: 100)

Example Request:

GET /api/reports/overview?env=live&from=2025-12-01&to=2025-12-31

Plan-Based Limits

Access to reporting features varies by subscription plan:

Plan Max Date Range Max Breakdown Items Advanced Reports Exports
Free 7 days 5 No No
Starter 30 days 10 No No
Growth 90 days 25 Yes Yes
Pro 90 days 100 Yes Yes
Enterprise 90 days 100 Yes Yes

Advanced Reports (Growth+ only):

V1 Endpoints

GET /api/reports/overview

Get dashboard summary metrics including total verifications, success rate, and product breakdown.

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "total_verifications": 1250,
    "pass_count": 1125,
    "fail_count": 125,
    "pass_rate": 90.0,
    "avg_confidence": 92.5,
    "by_product": {
      "verifyhuman": 800,
      "verifyage": 300,
      "verifyidentity": 100,
      "verifycompliance": 50
    },
    "by_status": {
      "PASS": 1125,
      "FAIL": 100,
      "ERROR": 25
    }
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "cached": false,
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/reports/volume

Get verification volume over time with configurable granularity.

Additional Parameters:

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "series": [
      {"date": "2025-12-01", "total": 45, "pass": 42, "fail": 3},
      {"date": "2025-12-02", "total": 52, "pass": 48, "fail": 4},
      {"date": "2025-12-03", "total": 38, "pass": 35, "fail": 3}
    ],
    "totals": {
      "total": 135,
      "pass": 125,
      "fail": 10
    }
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-03",
    "env": "live",
    "granularity": "day",
    "cached": false,
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/reports/usage

Get usage breakdown by product and API key.

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "by_product": [
      {"product": "verifyhuman", "count": 800, "percentage": 64.0},
      {"product": "verifyage", "count": 300, "percentage": 24.0},
      {"product": "verifyidentity", "count": 100, "percentage": 8.0},
      {"product": "verifycompliance", "count": 50, "percentage": 4.0}
    ],
    "by_api_key": [
      {"api_key_id": 1, "name": "Production Key", "count": 900, "pass_rate": 92.0},
      {"api_key_id": 2, "name": "Staging Key", "count": 350, "pass_rate": 88.0}
    ],
    "credits_consumed": {
      "verifyhuman": 800,
      "verifyage": 3000,
      "verifyidentity": 3000,
      "verifycompliance": 2500,
      "total": 9300
    }
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "cached": false,
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/reports/risk-summary

Get risk and confidence metrics. Requires Growth plan or higher.

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "confidence_distribution": {
      "high": {"min": 85, "max": 100, "count": 950, "percentage": 76.0},
      "medium": {"min": 70, "max": 84, "count": 200, "percentage": 16.0},
      "low": {"min": 0, "max": 69, "count": 100, "percentage": 8.0}
    },
    "failure_reasons": [
      {"reason": "No face detected", "count": 45, "percentage": 36.0},
      {"reason": "Low confidence score", "count": 35, "percentage": 28.0},
      {"reason": "Multiple faces detected", "count": 25, "percentage": 20.0},
      {"reason": "Liveness check failed", "count": 20, "percentage": 16.0}
    ],
    "avg_confidence": 92.5,
    "median_confidence": 94.0
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "cached": false,
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/reports/widget-performance

Get per-widget/API key performance analytics. Requires Growth plan or higher.

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "widgets": [
      {
        "api_key_id": 1,
        "name": "Signup Widget",
        "total": 500,
        "pass": 475,
        "fail": 25,
        "pass_rate": 95.0,
        "avg_confidence": 94.2,
        "avg_latency_ms": 1250
      },
      {
        "api_key_id": 2,
        "name": "Checkout Widget",
        "total": 300,
        "pass": 270,
        "fail": 30,
        "pass_rate": 90.0,
        "avg_confidence": 91.5,
        "avg_latency_ms": 1400
      }
    ]
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "cached": false,
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/reports/regulatory-coverage

Get compliance coverage metrics. Requires Growth plan or higher.

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "compliance_verifications": 50,
    "compliance_pass_rate": 88.0,
    "hit_rate": 12.0,
    "categories": [
      {"category": "PEP", "hits": 3},
      {"category": "Sanctions", "hits": 2},
      {"category": "AML", "hits": 1}
    ]
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "cached": false,
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

GET /api/reports/limits

Get current plan limits for reporting features.

Response (200):

{
  "schema_version": "1.0",
  "data": {
    "plan": "Growth",
    "max_date_range_days": 90,
    "max_breakdown_items": 25,
    "can_access_advanced_reports": true,
    "can_export_reports": true
  }
}

V2.1 Endpoints

V2.1 "Enterprise-Ready" endpoints provide advanced analytics with compliance effectiveness scoring, risk severity analysis, and role-gated credits intelligence.

Feature Flags:

GET /api/reports/v21/verification

Get verification analytics with compliance effectiveness scoring and risk severity breakdown.

Response (200):

{
  "schema_version": "2.1",
  "data": {
    "summary": {
      "total": 1250,
      "pass": 1125,
      "fail": 125,
      "pass_rate": 90.0,
      "avg_confidence": 92.5
    },
    "compliance_effectiveness_score": 87.5,
    "risk_severity": {
      "critical": {"min": 0, "max": 49, "count": 25, "percentage": 2.0},
      "high": {"min": 50, "max": 69, "count": 50, "percentage": 4.0},
      "medium": {"min": 70, "max": 84, "count": 175, "percentage": 14.0},
      "low": {"min": 85, "max": 100, "count": 1000, "percentage": 80.0}
    },
    "period_comparison": {
      "total_delta": 15.5,
      "pass_rate_delta": 2.3,
      "avg_confidence_delta": 1.2
    },
    "kpis": {
      "verification_volume": 1250,
      "success_rate": 90.0,
      "avg_response_time_ms": 1350,
      "credit_efficiency": 0.92
    },
    "daily_trend": [
      {"date": "2025-12-01", "count": 45, "pass": 42, "fail": 3}
    ],
    "health_checks": [
      {"check": "High failure rate", "status": "pass", "message": "Failure rate within normal range"}
    ]
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

Compliance Effectiveness Score Calculation:

GET /api/reports/v21/full

Get full report including credits intelligence. Credits section requires Owner, Admin, or Billing role.

Response (200):

{
  "schema_version": "2.1",
  "data": {
    "verification": {
      "summary": { "...": "..." },
      "compliance_effectiveness_score": 87.5,
      "risk_severity": { "...": "..." }
    },
    "credits": {
      "available": true,
      "snapshot": {
        "subscription_credits": 5000,
        "prepaid_credits": 2500,
        "total_available": 7500,
        "consumed_this_period": 9300,
        "projected_monthly_usage": 12000,
        "days_until_depletion": 18
      }
    },
    "widgets": [
      {"api_key_id": 1, "name": "Production", "total": 500, "risk_score": 12.5}
    ]
  },
  "meta": {
    "from": "2025-12-01",
    "to": "2025-12-31",
    "env": "live",
    "generated_at": "2025-12-31T23:59:59Z"
  }
}

Note: If user lacks credits view permission, credits.available will be false and credits.snapshot will be null.

Response Schema

All responses follow a consistent structure:

{
  "schema_version": "1.0 or 2.1",
  "data": { "...report data..." },
  "meta": {
    "from": "YYYY-MM-DD",
    "to": "YYYY-MM-DD",
    "env": "test or live",
    "cached": true/false,
    "generated_at": "ISO8601 timestamp"
  }
}

Error Handling

Validation Error (400):

{
  "error": "Date range exceeds plan limit of 30 days",
  "field": "date_range",
  "schema_version": "1.0"
}

Access Denied (403):

{
  "error": "Advanced reports require Growth plan or higher",
  "schema_version": "1.0"
}

Common Errors:

Error Cause Solution
'env' must be 'test' or 'live' Missing or invalid environment Specify env=test or env=live
'from' date is required Missing start date Add from=YYYY-MM-DD
Date range exceeds plan limit Date range too wide for plan Reduce range or upgrade plan
Advanced reports require Growth+ Accessing Growth-only endpoint on lower plan Upgrade to Growth or higher

See Also