Improvado Embedded API v3
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.
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
- 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
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)
- 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
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.)
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
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
titleanddescriptionfor each entry. - Create, rename, edit, and delete custom roles. System roles are read-only.
- List users currently assigned to a role for impact preview.
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)
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
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
idand asecret, and the endpoint is created inunverifiedstatus. - Verify ownership by calling the verify action. Improvado sends a GET request to your URL with
X-Improvado-Verify-TokenandX-Improvado-Challengeheaders. Your receiver must respond with HTTP 200 and the challenge value as the response body. After successful verification the endpoint moves toactive. - Receive events. Improvado POSTs JSON payloads
{id, type, timestamp, data}to your URL. Each request is signed with HMAC-SHA256 in theX-Improvado-Signatureheader (using the endpoint's secret) and includesX-Improvado-Idempotency-Keyfor safe retry handling. - Rotate the secret at any time. Rotation invalidates the previous secret immediately and resets the
endpoint to
unverifieduntil you re-verify.
[0s, 2s, 5s, 10s]. Receivers should aim to
respond within a few seconds and return 2xx for successful processing.