Integration API — Overview
The Survanta Integration API is a programmatic HTTP interface designed for external systems that need to read survey data from a tenant's Survanta account. Typical consumers are BI tools, data warehouses, reporting dashboards, ETL pipelines, and custom analytics applications built by the tenant or a third-party integrator.
Who Is This API For?
| Consumer type | Example |
|---|---|
| BI / reporting tools | Power BI, Tableau, Metabase pulling aggregate results |
| Data pipelines | Nightly ETL jobs extracting response data to a data lake |
| Custom dashboards | Tenant-built web apps showing survey KPIs |
| Third-party integrators | Vendors contracted to build analytics on behalf of a tenant |
Integration clients are not human dashboard users. They do not log in, do not hold ASP.NET Identity roles, and are not members of any permission group. They authenticate exclusively with an API key issued through the integration-client management surface by an authorized tenant administrator or an authorized platform user operating in a valid selected-tenant context.
What the Integration API Can Access
Access is controlled by the set of integration scopes granted to the client when the key is created. The available scopes are:
- ReportsRead — survey metadata and aggregate response summary endpoints.
- UsageRead — tenant integration usage summary endpoint.
- RawResponsesRead — individual response rows. This scope is sensitive and should only be granted when the integration contract explicitly requires it.
Every response is scoped to the tenant whose API key was used. A key issued by Tenant A cannot access data belonging to Tenant B.
How Authentication Works
All Integration API requests use the IntegrationApiKey authentication scheme and must include a valid key in the X-Survanta-Api-Key HTTP request header. Authentication requires an active, non-revoked, unexpired client, an active tenant, allowed subscription access, the client remaining within the effective External integrations, and plan-enabled scopes. ReportsRead and UsageRead require Report API access; RawResponsesRead requires Raw response API access. Successful authentication resolves tenant context, updates LastUsedAt, and writes an API-call audit row before the endpoint checks its required scope.
No cookie, no JWT bearer token, and no user session is involved in integration API authentication.
Relationship to the Permission System
Integration API scopes are a completely separate dimension from the System and Tenant permission model used by dashboard users. Scopes are stored on the integration client record, not in permission groups, and they have no interaction with RequirePermission enforcement on dashboard routes.
Base URL
All integration endpoints are served under the /api/integrations/ path prefix on the same host as the Survanta dashboard. The exact host is determined by your tenant's deployment.
Versioning
The API is currently unversioned. No repository-backed guarantee about a separate advance-notice channel is part of the current API contract, so consumers should validate response contracts when upgrading.