Statistics API

The Statistics API provides aggregated data about your documents and signing activity. Use this endpoint to build dashboards, reports, and monitor your signing workflows.

Get Statistics

Retrieve document statistics for the current user (or all documents for admins).

GET /wp-json/wpsigner/v1/stats

Example Request

curl -X GET "https://your-site.com/wp-json/wpsigner/v1/stats" \
  -H "X-WPS-API-Key: wps_your_key" \
  -H "X-WPS-API-Secret: your_secret"

Response

{
  "total": 150,
  "draft": 25,
  "sent": 10,
  "viewed": 5,
  "completed": 100,
  "declined": 5,
  "expired": 3,
  "deleted": 2
}

Response Fields

Field	Type	Description
total	integer	Total number of documents
draft	integer	Documents in draft status
sent	integer	Documents sent, awaiting signatures
viewed	integer	Documents viewed by at least one signer
completed	integer	Fully signed documents
declined	integer	Documents with at least one decline
expired	integer	Expired documents
deleted	integer	Soft-deleted documents

---

Understanding Statistics

Document Lifecycle

Documents progress through these stages:

draft → sent → viewed → completed
                ↓           ↓
            declined    expired

Status Definitions

Status	Criteria
draft	Created but not sent to signers
sent	Sent to signers, no views yet
viewed	At least one signer has opened the document
completed	All required signatures collected
declined	At least one signer declined
expired	Past the expiration date without completion

---

User vs Admin Stats

Regular Users

API keys associated with non-admin users return statistics for their own documents:

{
  "total": 15,
  "completed": 10,
  ...
}

Administrators

API keys associated with WordPress administrators return global statistics:

{
  "total": 500,
  "completed": 350,
  ...
}

---

Use Cases

Dashboard Integration

Display signing metrics in your dashboard:

async function fetchStats() {
  const response = await fetch('/wp-json/wpsigner/v1/stats', {
    headers: {
      'X-WPS-API-Key': API_KEY,
      'X-WPS-API-Secret': API_SECRET
    }
  });

  const stats = await response.json();

  // Calculate completion rate
  const completionRate = (stats.completed / stats.total * 100).toFixed(1);

  // Calculate pending documents
  const pending = stats.sent + stats.viewed;

  return {
    ...stats,
    completionRate,
    pending
  };
}

Monitoring & Alerts

Set up monitoring for low completion rates:

async function checkMetrics() {
  const stats = await fetchStats();

  // Alert if too many documents expired
  if (stats.expired > 10) {
    sendAlert('High number of expired documents!');
  }

  // Alert on high decline rate
  const declineRate = stats.declined / stats.total;
  if (declineRate > 0.1) {
    sendAlert('Decline rate above 10%');
  }
}

Reporting

Generate weekly reports:

async function generateReport() {
  const stats = await fetchStats();

  return {
    period: 'This Week',
    metrics: {
      'Total Documents': stats.total,
      'Completed': stats.completed,
      'Pending': stats.sent + stats.viewed,
      'Declined': stats.declined,
      'Completion Rate': `${(stats.completed / stats.total * 100).toFixed(1)}%`
    }
  };
}

---

Caching Considerations

The stats endpoint queries the database in real-time. For high-traffic applications:

Client-Side Caching

let statsCache = null;
let cacheTime = 0;
const CACHE_TTL = 60000; // 1 minute

async function getStats() {
  const now = Date.now();

  if (statsCache && (now - cacheTime) < CACHE_TTL) {
    return statsCache;
  }

  statsCache = await fetchStats();
  cacheTime = now;

  return statsCache;
}

Recommended Polling Interval

Use Case	Interval
Dashboard refresh	60 seconds
Background monitoring	5 minutes
Daily reports	Once per day

---

Error Responses

Authentication Required

{
  "code": "rest_forbidden",
  "message": "Invalid API key or secret.",
  "data": {
    "status": 401
  }
}

Rate Limit Exceeded

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait 30 seconds.",
  "data": {
    "status": 429,
    "retry_after": 30
  }
}