PPactDocs
CRM

Reports

The custom report builder — pick an entity, choose metrics and group-bys, save, run, chart, export, schedule, and share.

Reports

Reports is Pact's self-serve report builder. You pick an entity (accounts, contacts, opportunities, and more), choose metrics and group-bys, apply filters, and save a runnable report definition. Saved reports can be charted, exported to CSV / XLSX / PDF, emailed on a schedule, and shared via a public token. The surface is backed by /v1/reports (api/routes/reports.py) and the core.reports package; the builder logic lives in core.reports.builder.

Analytics module

Every report route requires verify_api_key and is tenant-scoped through get_tenant_id — the report store enforces the tenant predicate on every read and write. All routes except the static template catalog (GET /v1/reports/templates, verify_api_key only) additionally require require_module("analytics"). The public share endpoint (see Report detail) is the one route with no API-key gate at all — it is token-gated instead.

Reportable entities

GET /v1/reports/entities returns the schema the builder picker renders. The entity set is declared in core.reports.builder.ENTITIES:

  • accounts — companies, with CRM-stage and firmographic filters.
  • contacts — with title, account_role, company_name filters.
  • opportunities — with stage, owner, forecast_category filters.
  • sequence_events — outbound engagement, filterable by event_type, channel, provider.
  • timeline — activity events, filterable by event_type, actor.
  • consent — consent records, for compliance reporting.

Each entity exposes columns, groupable, and filterable field lists so the builder can only offer valid choices. Per-entity column introspection is available via GET /v1/reports/entities/{entity_key} (backed by core.reports.builder.available_columns).

Metrics, group-bys, and chart types

A report definition (ReportDefinition) is a list of metrics — (agg, column) pairs — plus optional group-bys, filters, and a chart_type. A report with neither group-by nor metrics is a plain list report. Chart types are fixed in core.reports.builder.CHART_TYPES: table, bar, line, area, pie, kpi, funnel. An unknown chart type is rejected at validation time. GET /v1/reports/chart-types returns the enum for the picker.

Build from a sentence, or from a template

Natural-language generation

POST /v1/reports/ai/generate turns a plain-English ask ("weekly pipeline by rep") into a validated, runnable report definition. When the tenant has an AI provider configured it uses the model; otherwise a deterministic keyword heuristic (core.reports.ai) produces a sensible starting point — so the endpoint always returns a valid definition for a non-empty prompt. The response flags ai_powered, used_fallback, and not_configured so the UI can be honest about which path produced the result.

GET /v1/reports/templates returns pre-built template definitions, and POST /v1/reports/{template_id}/from-template clones one into your saved reports.

CRUD, run, and live preview

  1. 1

    Create

    POST /v1/reports with a name, optional description, and a definition.
  2. 2

    List / read

    GET /v1/reports and GET /v1/reports/{id}.
  3. 3

    Edit

    PATCH /v1/reports/{id} — partial update of name, description, or definition.
  4. 4

    Run

    POST /v1/reports/{id}/run executes the saved definition and returns columns, rows, and count; it stamps last_run_at and fires a report.ready notification to the caller.
  5. 5

    Preview

    POST /v1/reports/preview runs an unsaved definition — this powers the live-preview pane in the builder.

Head to Report detail for the full run / export / schedule / share walkthrough on a single saved report.

Report detailRun, chart, export, schedule, and share one saved report.AnalyticsPrebuilt dashboards across the platform.JourneysMulti-step automation whose engagement feeds sequence_events.ConsentThe consent entity you can report on for compliance.