Improvado Embedded API v3

Download schema

Improvado Embedded API V3 provides programmatic access to data extraction, transformation, and loading capabilities.

Authentication

This API supports multiple authentication methods depending on the endpoint:

Basic Authentication

Used for workspace-agnostic operations such as:

Creating access tokens (POST /api/v3/token)
Listing workspaces (GET /api/v3/workspaces)
Managing workspaces (POST /api/v3/workspaces, GET /api/v3/workspaces/{id}, PUT /api/v3/workspaces/{id})
Getting iframe URLs (POST /api/v3/get_iframe_url)
Listing available recipes (GET /api/v3/recipes/) etc.

Format: Authorization: Basic <base64(username:password)>

Bearer Token Authentication

Used for workspace-scoped operations after obtaining a token from /api/v3/token. The token is scoped to a specific workspace.

Format: Authorization: Bearer <token>

Cookie Authentication

Alternative to Bearer token for browser-based integrations. When using cookie authentication, you must include the workspace ID in the request header.

Cookie: dts_session_id=<session_token>

Required Header: X-IM-WORKSPACE-ID: <workspace_id>

Workspace Scoping

Most API operations are workspace-scoped. After authenticating with Basic Auth, obtain a workspace-specific token using POST /api/v3/token with the desired workspace_id. This token provides access only to resources within that workspace, ensuring isolation between different customers or projects.

Errors

The automated recipe operations under /api/v3.1/automated-recipe* and GET /api/v3.1/connections/{connection_id}/accounts/ return errors as {"code": "...", "message": "...", "details": {...}}. Branch on code, never on the message text. See Errors for the catalogue of codes and the shape of details.

All other operations return errors as {"detail": "error description"}.

Tags

Authentication

Authentication and authorization endpoints for the Improvado Embedded API. Authentication supports Basic Auth (username:password) for initial token creation, then Bearer tokens for workspace-scoped operations.

Data sources

Browse and configure available data sources for extraction. Data sources represent the marketing platforms, advertising networks, analytics tools, and other systems from which Improvado can extract data (e.g., Google Ads, Facebook Ads, Salesforce).

Data source connections

Manage connections to data sources for authentication and data access. Connections handle authentication with data sources and maintain the credentials needed for data extraction. Connections are typically created through the iframe UI, where users can:

Provide username/password credentials
Complete OAuth flows
Configure additional connection parameters

Connection lifecycle:

Create connection via iframe (provides OAuth or credential input)
Validate connection status
Use connection to create extracts
Monitor connection health and refresh tokens as needed

Accounts

Manage connection accounts from which data is extracted. Accounts represent specific accounts within a data source platform. Each account is associated with a connection and can have multiple extracts configured to pull data from it.

Extraction templates

Work with predefined templates that define what data to extract from a data source. Extract templates are blueprints that specify:

Available fields from a data source
Default extraction settings and parameters
Supported date ranges and filters

Global templates are created and maintained by Improvado. When you create an extract, you select a template and optionally customize its settings for your specific use case.

Extracts

Create and manage data extraction orders that pull data from connected sources. An extract represents a configured instance of data extraction with specific settings:

Which connection and account to extract from
Which extract template to use
Custom field selections and filters
Schedule and date range configuration
Where to store the extracted data (data table)

Extract workflow:

Create extract with desired configuration
Extraction runs automatically on schedule or on-demand
Data is stored in the associated data table
Monitor extraction status and history

Data tables

Manage data tables where extracted data is stored and organized. Data tables serve as centralized storage for extracted data. All extractions created from the same extract template are stored in the same data table, providing a unified view of your data. Data tables are also used as sources when configuring loads to destinations.

Destinations

Manage available destination options where Improvado can load your data. Destinations represent the target systems where extracted and transformed data is loaded, including:

Data warehouses (Snowflake, BigQuery, Redshift)
Databases (PostgreSQL, MySQL)
File storage (S3, Google Cloud Storage)
Business intelligence tools

Destination connections

Configure and manage connections to destinations for data loading. Destination connections define how and where data should be loaded within a destination system. They include:

Authentication credentials for the destination
Target configuration (database, schema, table naming patterns)
Load behavior settings (append, replace, upsert)
Path and formatting rules

Destination connections are created and modified through the iframe UI to securely handle credentials.

Loads

Configure and manage data loading from data tables to destinations. Load orders define the rules and settings for how data moves from Improvado's data tables to your destination systems. This includes:

Source data table selection
Destination connection and target location
Load schedule and frequency
Data transformation and mapping rules
Load mode (full refresh, incremental, etc.)

Loads ensure your data is automatically synchronized from Improvado to your destination on the schedule you define.

iframe

Generate secure iframe URLs for embedded UI components. iframe endpoints provide secure, embeddable UI components for:

Creating and managing data source connections (OAuth flows, credential input)
Configuring destination connections
Managing connection settings and permissions

These IFrames handle sensitive operations like authentication in a secure, pre-built UI that you can embed directly into your application.

Roles

Manage custom workspace roles and inspect the available permission catalog. Each agency ships with a fixed set of system roles (Workspace Admin, Editor, Viewer, Data Manager, Data Load Manager, Data Analyst). On top of these you can define custom roles scoped to the agency and assign them to users in any workspace. Capabilities:

List system + custom roles (each role carries its assigned user_count).
Fetch the curated permission catalog: a stable, ordered list of product layers with permissions, including human-readable title and description for each entry.
Create, rename, edit, and delete custom roles. System roles are read-only.
List users currently assigned to a role for impact preview.

Delete semantics: deleting a custom role atomically reassigns every user holding it to the system Viewer role; the response returns reassigned_users_count. All Roles endpoints require an agency-chief Basic Auth credential and the can_use_embedded_api flag enabled for the agency.

Workspaces

Manage workspaces that provide isolated environments for organizing resources. Workspaces are fundamental to multi-tenancy in Improvado's Embedded API. Each workspace provides complete isolation of resources including connections, extracts, data tables, and loads. Use workspaces to:

Separate resources for different customers or projects
Maintain data isolation and security boundaries
Control access through workspace-scoped tokens
Organize resources by environment (dev, staging, production)

Important: Access tokens are scoped to a specific workspace. A token for one workspace cannot access resources in another workspace, ensuring strict isolation between tenants.

Recipes

Work with pre-built recipes that automate common data pipeline workflows. Recipes are templated workflows that combine multiple API operations into reusable patterns. They simplify common tasks like:

Setting up end-to-end data pipelines (source → extract → load → destination)
Configuring multiple related extracts at once
Applying best-practice configurations

Recipes accelerate implementation by providing proven patterns for common use cases. Automated recipes have moved to v3.1. They are documented under Automated Recipes, which is where new integrations should start. The /api/v3/automated-recipe-templates/ and /api/v3/automated-recipes/ operations in this tag are deprecated. They keep working until they are switched off, and we will announce the date in advance. See Moving recipes to v3.1 for what changes between the two versions, and Deploying recipes for the current flow. Two operations in this tag are not automated recipes and are not deprecated: List agency recipes (GET /api/v3/recipes/) and Enable recipe in a workspace (POST /api/v3/workspaces/{id}/recipes). They use Basic authentication, work with the recipes available to your agency rather than with automated recipes, and have no v3.1 replacement.

Automated Recipes

Deploy and operate automated recipes through the v3.1 API. An automated recipe turns a template into a SQL view in your workspace destination, built from the extractions the template needs. Deploying a recipe takes four calls, in this order:

GET /api/v3.1/automated-recipe-templates/ - pick a template.
POST /api/v3.1/automated-recipes/ - create the recipe. It is created empty.
PUT /api/v3.1/automated-recipes/{recipe_id}/ - supply data sources, connections and accounts. This step is mandatory.
POST /api/v3.1/automated-recipes/{recipe_id}/build/ - start the build, then poll GET /api/v3.1/automated-recipes/{recipe_id}/ until state is ready_to_work or failed.

Every path ends with a slash; a 301 means the slash is missing from your URL. With a bearer token the workspace is the one the token was issued for; with cookie authentication, send the workspace id in the X-IM-WORKSPACE-ID header. All errors use one envelope - see Errors. See the Deploying recipes guide for the full flow.

Webhooks

Manage webhook endpoints that receive event notifications from Improvado. Webhooks let your application react to platform events (extraction completion, load completion, etc.) in near real time, without polling. Each endpoint is workspace-scoped and subscribes to one or more event types. Lifecycle:

Register an endpoint with the URL of your receiver and the event types you care about. Improvado returns an id and a secret, and the endpoint is created in unverified status.
Verify ownership by calling the verify action. Improvado sends a GET request to your URL with X-Improvado-Verify-Token and X-Improvado-Challenge headers. Your receiver must respond with HTTP 200 and the challenge value as the response body. After successful verification the endpoint moves to active.
Receive events. Improvado POSTs JSON payloads {id, type, timestamp, data} to your URL. Each request is signed with HMAC-SHA256 in the X-Improvado-Signature header (using the endpoint's secret) and includes X-Improvado-Idempotency-Key for safe retry handling.
Rotate the secret at any time. Rotation invalidates the previous secret immediately and resets the endpoint to unverified until you re-verify.

Failed deliveries are retried up to four times with backoff [0s, 2s, 5s, 10s]. Receivers should aim to respond within a few seconds and return 2xx for successful processing.

Servers

https://embedded.improvado.io