VisionAtlas — Navigate Performance With Clarity

Help center

VisionAtlas product documentation

Try demoSign in
← All articles

Performance

Capturing KPI actuals

Manual entry, bulk CSV import, API integration, and webhooks for KPI actual values by reporting period.

VisionAtlas stores KPI actuals per reporting period. Each KPI has a reporting frequency (Weekly, Monthly, or Quarterly) that determines how dates map to period buckets.

For KPI concepts and linking, see KPIs.

Manual entry

  1. Open KPIs and select a KPI.
  2. Update Current value (the latest actual).
  3. Save changes.

The app records the value for the current reporting period based on the KPI frequency and your company fiscal calendar (Settings).

Bulk CSV import

Users with permission to create KPIs can import historical actuals from KPIs → Import KPI actuals.

CSV columns (use kpi_id or external_source + external_metric_id):

  • kpi_id — KPI id from the KPI detail URL
  • external_source — e.g. ERP, Salesforce (must match KPI integration mapping)
  • external_metric_id — external system's metric identifier
  • period_start — any date (YYYY-MM-DD) within the target period
  • actual_value — number
  • target_value — optional override for that period

Download the template from the import card. Rows that fail validation are reported; conflicts may be queued for admin review in Settings → Integrations.

API integration

API access requires a plan that includes API access (Intelligence+). Company administrators create API keys under Settings → Integrations & API keys.

OpenAPI specification

Full request/response schemas are documented in the OpenAPI spec:

  • In-app: open /api/openapi in your browser (YAML)
  • Use this when building integrations or reviewing available endpoints

List KPIs

GET /api/v1/kpis
Authorization: Bearer va_live_...

Returns KPI ids, names, reporting frequencies, external mapping fields, validation rules, and current values.

Optional filters: externalSource (all KPIs from that source), or externalSource + externalMetricId for an exact mapping lookup.

Export actual history

GET /api/v1/kpi-values?since=2026-01-01&limit=500
Authorization: Bearer va_live_...

Optional filters: kpiId, externalSource + externalMetricId, since (YYYY-MM-DD), limit (max 1000).

Use externalSource and externalMetricId when you do not store VisionAtlas internal KPI ids. For API integrations, prefix metric IDs with the system name (e.g. netsuite:REV_MTD).

Submit actuals

POST /api/v1/kpi-values
Authorization: Bearer va_live_...
Content-Type: application/json

{
  "values": [
    {
      "externalSource": "ERP",
      "externalMetricId": "NET_REVENUE_USD",
      "asOfDate": "2026-05-15",
      "actualValue": 42.5,
      "targetValue": 50
    }
  ]
}

Use kpiId or externalSource + externalMetricId. Use asOfDate for any date within the period, or periodStart with the exact period start date.

Manual edits win over automated ingestion for the same period. Rows that conflict are queued for review in Settings → Integrations.

Low-code playbooks

See Integration playbooks for Power Automate, Zapier, and n8n recipes.

Analytics export

See Analytics export for Power BI and semantic model documentation.

Webhooks

Company administrators can configure webhooks under Settings → Webhooks (when API access is enabled):

  • Subscribe to events such as KPI value updates
  • VisionAtlas POSTs signed payloads to your endpoint
  • Review delivery history in Settings for failed deliveries

Webhooks complement polling — use them to sync downstream systems when actuals change.

How periods work

  • Weekly KPIs use your company week starts on setting.
  • Monthly and Quarterly KPIs use your fiscal year start from Settings.
  • The KPI list and dashboard show current value from the most recent period with data.

Related