Integration playbooks

Use these playbooks when you want ERP, BI, or spreadsheet systems to feed VisionAtlas without building a custom connector.

Prerequisites

1. Intelligence+ plan with API access enabled
2. Company administrator creates an API key under Settings → Integrations & API keys
3. Map each KPI to an external metric on the KPI detail page (Integration mapping), or use internal kpiId values from GET /api/v1/kpis
4. Review the OpenAPI spec at /api/openapi

Authentication

All requests use a Bearer token:

Authorization: Bearer va_live_...

Submit actuals (all playbooks)

POST /api/v1/kpi-values
Content-Type: application/json

{
  "values": [
    {
      "externalSource": "ERP",
      "externalMetricId": "NET_REVENUE_USD",
      "asOfDate": "2026-07-01",
      "actualValue": 1250000,
      "targetValue": 1200000
    }
  ]
}

You may use kpiId instead of externalSource + externalMetricId. Use asOfDate for any date within the reporting period, or periodStart with the exact period start date.

Response semantics

• totalSuccess — values written
• totalSkipped — rows skipped (validation, manual precedence)
• totalConflicts — rows queued for admin review in Settings → Integrations
• importJobId — track the run in import history

Manual KPI edits win over automated ingestion for the same period unless an admin accepts a queued conflict.

Power Automate

1. Create a scheduled cloud flow (e.g. every Monday 6:00 AM)
2. Add your source action (SQL query, Dataverse list rows, SharePoint export)
3. Add HTTP action:

- Method: POST - URI: https://your-tenant.visionatlas.app/api/v1/kpi-values - Headers: Authorization: Bearer {your-key}, Content-Type: application/json - Body: map dataset columns to the JSON values array

1. Parse the response and alert if totalErrors or totalConflicts > 0

Sample payload: docs/integrations/sample-kpi-values-payload.json

Zapier

1. Trigger: Schedule or your app trigger (Google Sheets, Salesforce, etc.)
2. Action: Webhooks by Zapier → POST
3. URL: https://your-tenant.visionatlas.app/api/v1/kpi-values
4. Payload type: JSON
5. Map fields to values[0].externalMetricId, values[0].actualValue, values[0].asOfDate

n8n

1. Use Cron + source node (Postgres, HTTP Request, Google Sheets)
2. Add HTTP Request node targeting POST /api/v1/kpi-values
3. Authentication: Header Auth with Authorization: Bearer va_live_...
4. Reference workflow outline: docs/integrations/n8n-kpi-sync.md

CSV alternative

For ad-hoc backfills, use KPIs → Import KPI actuals with:

external_source,external_metric_id,period_start,actual_value,target_value
ERP,NET_REVENUE_USD,2026-07-01,1250000,1200000

Scheduled pull (built-in)

Under Settings → Integrations & API keys → Scheduled integrations, admins can configure:

Scheduled CSV and Google Sheets syncs run automatically when VisionAtlas cron calls POST /api/cron/kpi-integration-sync (same CRON_SECRET as other cron jobs). Use Run now in Settings to test immediately.

CSV columns match the manual import format (kpi_id or external_source + external_metric_id, period_start, actual_value, optional target_value).

Webhook ingest endpoint

Create a Webhook ingest integration to receive a dedicated secret (vi_ingest_…). POST batches without a company API key:

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

{
  "values": [
    {
      "externalSource": "ERP",
      "externalMetricId": "NET_REVENUE_USD",
      "asOfDate": "2026-07-01",
      "actualValue": 1250000
    }
  ]
}

The ingest secret is shown once at creation. Manual KPI edits still win over automated values unless an admin accepts a queued conflict.

Related

• Capturing KPI actuals
• Analytics export