Dashboard

Report Exports API

Last Updated: January 5, 2026
API Version: 2.1.0
Feature Flag: REPORT_EXPORTS_ENABLED
Plan Requirement: Growth, Pro, or Enterprise

The Report Exports API allows you to create, manage, and download verification reports in PDF or CSV format. Export jobs are processed asynchronously and can be monitored for completion status.

Table of Contents

Overview

The export workflow follows these steps:

  1. Create Job - Submit export request with report type, date range, and format
  2. Monitor Status - Poll job status or wait for completion
  3. Download - Download the completed export file
  4. Cleanup - Files are automatically cleaned up after 24 hours

Key Features:

Authentication

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

Plan Requirements

Export functionality is available on Growth plan and higher:

Plan Export Access PDF Exports
Free No No
Starter No No
Growth Yes Yes
Pro Yes Yes
Enterprise Yes Yes

Endpoints

POST /api/reports/exports

Create a new export job.

Request Body:

{
  "report_type": "overview",
  "format": "pdf",
  "env": "live",
  "from": "2025-12-01",
  "to": "2025-12-31"
}

Parameters:

Field Type Required Description
report_type String Yes Report type (see Report Types)
format String No pdf or csv (default: pdf)
env String Yes Environment: test or live
from String Yes Start date YYYY-MM-DD
to String Yes End date YYYY-MM-DD

Response (201):

{
  "id": 123,
  "report_type": "overview",
  "format": "pdf",
  "status": "queued",
  "params": {
    "env": "live",
    "from": "2025-12-01",
    "to": "2025-12-31"
  },
  "created_at": "2025-12-31T10:00:00Z"
}

GET /api/reports/exports

List your export jobs.

Query Parameters:

Response (200):

{
  "exports": [
    {
      "id": 123,
      "report_type": "overview",
      "format": "pdf",
      "status": "succeeded",
      "file_size_bytes": 245760,
      "created_at": "2025-12-31T10:00:00Z",
      "completed_at": "2025-12-31T10:01:30Z"
    },
    {
      "id": 122,
      "report_type": "usage",
      "format": "csv",
      "status": "succeeded",
      "file_size_bytes": 15360,
      "created_at": "2025-12-30T15:00:00Z",
      "completed_at": "2025-12-30T15:00:45Z"
    }
  ],
  "total": 2,
  "page": 1,
  "pages": 1
}

GET /api/reports/exports/{id}

Get the status of a specific export job.

Response (200):

{
  "id": 123,
  "report_type": "overview",
  "format": "pdf",
  "status": "succeeded",
  "params": {
    "env": "live",
    "from": "2025-12-01",
    "to": "2025-12-31"
  },
  "file_size_bytes": 245760,
  "created_at": "2025-12-31T10:00:00Z",
  "completed_at": "2025-12-31T10:01:30Z",
  "download_url": "/api/reports/exports/123/download"
}

GET /api/reports/exports/{id}/download

Download a completed export file.

Requirements:

Response (200):

Error (404):

{
  "error": "Export file not found or expired"
}

DELETE /api/reports/exports/{id}

Cancel a queued export job. Cannot cancel running or completed jobs.

Response (200):

{
  "message": "Export job cancelled",
  "id": 123
}

Error (400):

{
  "error": "Cannot cancel export with status: running"
}

Report Types

Available report types for export:

Report Type Description Plan Required
overview Dashboard summary metrics Growth+
volume Volume over time Growth+
usage Usage by product/API key Growth+
risk-summary Risk and confidence metrics Growth+
widget-performance Per-widget analytics Growth+
full Complete V1 report Growth+
verification-v21 V2.1 verification analytics Growth+
full-v21 V2.1 full report with credits Growth+

Export Formats

PDF Format

Professional, print-ready reports with:

V2.1 PDF Reports include:

CSV Format

Raw data export for:

CSV exports include all data points without visualizations.

Job Status

Export jobs progress through these statuses:

Status Description
queued Job created, waiting to process
running Currently generating report
succeeded Complete, ready for download
failed Error occurred during generation

Status Flow:

queued → running → succeeded
                 ↘ failed

Error Handling

Validation Error (400):

{
  "error": "Invalid report_type. Must be one of: overview, volume, usage, risk-summary, widget-performance, full, verification-v21, full-v21",
  "field": "report_type"
}

Access Denied (403):

{
  "error": "Export functionality requires Growth plan or higher"
}

Not Found (404):

{
  "error": "Export job not found"
}

Common Errors:

Error Cause Solution
Invalid report_type Unknown report type Use valid report type
Invalid format Not pdf or csv Specify format=pdf or format=csv
Date range exceeds plan limit Range too wide Reduce date range
Export requires Growth plan On Free/Starter plan Upgrade plan
Cannot cancel: running Job already started Wait for completion
File not found or expired File deleted after 24h Create new export

Example Workflow

1. Create Export

curl -X POST https://app.verifyhuman.io/api/reports/exports \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "verification-v21",
    "format": "pdf",
    "env": "live",
    "from": "2025-12-01",
    "to": "2025-12-31"
  }'

2. Check Status

curl https://app.verifyhuman.io/api/reports/exports/123

3. Download When Complete

curl -O https://app.verifyhuman.io/api/reports/exports/123/download

See Also