Changelog

API Changelog

August 19, 2026

Documented: the full webhook event catalog

All 90 event types that GET /api/v3/webhook_event_types/ can return are now enumerated in the spec, and each one is documented with the payload you actually receive on the new Webhook Events page.

event_types (when creating or updating an endpoint) and event_name (in the event-type response) now carry the full enum, so the reference lists valid values and generated clients validate them.
The delivered data object is shaped by the event's aggregate class, not by the event type — 12 shapes cover all 90 events. Match on the shape rather than on each event name.
All payload values are strings. A field documented as empty is empty in production for that event type; it is not an omission. Notably extraction_completed carries no status or error, and transformation_completed never carries mcdm_recipe_title.
17 event types are marked silent: valid to subscribe to, but they produced no events in a 30-day production sample. Do not build a flow that waits on one.

No behaviour changed — this documents what the API already sends.

August 12, 2026

Added: Account selection in the connection iframe

Append show_account_selection=True to the URL returned by POST /api/v3/get_iframe_url to let the end user choose which accounts a connection syncs, instead of creating a connection that syncs all of them.

The flow becomes two steps: the user authorizes first, then either syncs all accounts or picks specific ones, and the connection is created from that choice.
ConnectionCreated is posted to the parent window only after the account step, so the connection already exists when your page receives it.
Add the parameter to the returned URL yourself — get_iframe_url does not emit it.
Data sources that cannot list accounts before the connection exists keep the single-step flow, and the parameter has no effect there.

Existing embeds are unaffected: without the parameter the iframe behaves exactly as before.

July 14, 2026

Added: Update a data table (field selection)

New PUT /api/v3/data-tables/{data_table_id} operation that controls which fields (columns) of a data table are delivered by its loads to the destination.

Request body takes selected_fields — the full list of field name values (as returned by the detail endpoint's fields[].name) that should be selected; any field not listed becomes deselected.
Field selection is set at the data table level and affects all loads delivering this data table. Unknown field names are ignored; dimension fields cannot be deselected (returns 400).
Returns the same DataTableDetail payload as GET /api/v3/data-tables/{data_table_id}, so clients can confirm the resulting selection without a follow-up read.

Added: External authentication links

New endpoints that let you request data source credentials from an external user — the API equivalent of the platform UI action "Request credentials from another user":

POST /api/v3/datasources/{datasource_name}/external-auth-links — generates one-time links (one per email in to_emails) that let an external user, such as the end client of an agency, authenticate a connection with their own credentials and select which accounts to grant, without having access to the workspace. Links are single-use, expire after 14 days, and can be revoked; set send_email: false to deliver the links yourself instead of having Improvado email them.
GET /api/v3/datasources/{datasource_name}/external-auth-links — lists the generated links with their current status (not_used, used, expired, revoked_manually).
POST /api/v3/datasources/{datasource_name}/external-auth-links/{id}/revoke — revokes a not-yet-used link.

Requires the agency feature flag for external authentication links (contact Improvado to enable it); the endpoint returns 403 otherwise.

June 15, 2026

Changed: Extraction template validation request format

POST /api/v3/extract-template/{template_id}/validation/ now takes a new request body shaped around embedded accounts:

accounts is now a non-empty list of embedded account IDs (integers) instead of remote account ID strings. The connection is resolved automatically from the accounts, which must all belong to a single connection.
Field, custom-setting, dynamic-field, custom-filter and historical-backfill inputs now live under an optional template_settings object (fields, additional_params, dynamic_fields, custom_filters, sync_historical_data).
The top-level connection_id, fields, custom_settings and string accounts fields have been removed.
Returns 400 when accounts span multiple connections or reference accounts that do not exist.

Added: Get extraction template by id

GET /api/v3/extract-template/{template_id}/ — returns a compact template representation (id, datasource_name, is_wide_template), useful for choosing the right extract flow before creating or migrating an extract.

Added: Account identifiers on extract objects

Extract responses (GET /api/v3/extracts, GET /api/v3/extracts/{id}, and create / PUT / PATCH responses) now include:

account_entity_id — internal Improvado account entity ID
account_embedded_id — embedded account ID (nullable when the account is not linked to an embedded account)

June 5, 2026

Added: Wide report extract migration

New endpoints supporting non-destructive dimension changes on wide report extracts. Changing dimensions on a wide report requires a data table with a new schema, so instead of editing the extract in place, the API creates a new extract with a new data table and pauses the original — its data stays queryable.

POST /api/v3/extracts/migrate-wide — migrate a wide report extract with changed dimensions to a new extract. Only migrated_from_extraction_id and template_settings are required; every omitted setting is pre-filled from the source extract, and the response returns the new extract's detail.
POST /api/v3/extract-template/{template_id}/validation/ — pre-flight validation of the proposed fields / custom_settings / accounts combination against a template before creating or migrating an extract.

Changed: is_wide_template flag on extract template objects

The template object in extract responses (GET /api/v3/extracts, GET /api/v3/extracts/{id}, and PUT / PATCH responses) now includes a boolean is_wide_template field, so clients can detect wide report extracts and route dimension changes through the migrate-wide flow.

May 21, 2026

Added: Roles & Permissions API

New endpoints for managing custom workspace roles and inspecting the available permission catalog:

GET /api/v3/roles/ — list system + agency-custom roles (each carries user_count)
GET /api/v3/roles/permissions — ordered catalog of product layers and permissions, each with human-readable title and description
GET /api/v3/roles/{role_id} — retrieve a role
GET /api/v3/roles/{role_id}/users — list users assigned to a role (with workspace), useful for impact preview
POST /api/v3/roles/ — create a custom role
PATCH /api/v3/roles/{role_id} — update title, description, or permissions of a custom role
DELETE /api/v3/roles/{role_id} — delete a custom role; users assigned to it are atomically reassigned to the system Viewer role, response includes reassigned_users_count

System roles are read-only. All endpoints require Basic Auth as an agency chief, and the agency must have the embedded API enabled.

May 5, 2026

Added: enabled_for_extraction_accounts_number on List Connections

New response field on GET /api/v3/datasources/{datasource_name}/connections that returns the number of accounts on each connection that are selected for extraction.

Pairs with the existing accounts_number (total accounts) — clients can detect connections with enabled_for_extraction_accounts_number == 0 and prompt the user to select accounts before setting up extractions or loads.
Removes the need to fan out a per-connection GET /accounts call to compute this client-side.

April 28, 2026

Added: Custom Setting Options endpoint

New endpoint for loading dynamic options for select-based extraction custom settings:

POST /api/v3/datasources/{datasource_name}/custom_setting_options/
Resolves options for one or more source accounts using connection_id
Accepts remote account ID strings in account_ids, matching extraction template preview
Supports server-side search and pagination over loaded option lists
Returns options grouped by account using the standard paginated-response shape (count, next, previous, results)

April 27, 2026

Added: Webhooks API

New endpoints for managing webhook endpoints that receive event notifications from Improvado:

GET / POST /api/v3/webhook_endpoints/ — list and register webhook endpoints
GET / PATCH / DELETE /api/v3/webhook_endpoints/{id}/ — retrieve, update, and delete an endpoint
POST /api/v3/webhook_endpoints/{id}/verify/ — verify endpoint ownership via challenge-response
POST /api/v3/webhook_endpoints/{id}/regenerate_secret/ — rotate the signing secret
GET /api/v3/webhook_event_types/ — list available event types

Each endpoint is workspace-scoped, signs deliveries with HMAC-SHA256 in the X-Improvado-Signature header, and supports automatic retries with backoff on failed deliveries.

April 15, 2026

Added: Filter parameters for List Extracts endpoint

New optional query parameters on GET /api/v3/extracts to narrow results on the server side:

connection_id — filter by connection ID (single value or comma-separated list)
datasource_name — filter by datasource name, e.g. reddit or reddit,facebook
data_table_id — filter by data table ID (single value or comma-separated list)

Lets clients avoid paginating the full list and filtering locally.

April 2, 2026

Added: Create Extract Template endpoint

New endpoint for creating extraction templates programmatically.

POST /api/v3/datasources/{datasource_name}/extract-templates/
Supports standard and wide report template creation
Wide report templates require connection_id and validate fields against the DSAS API
Includes detailed error response examples for common validation failures

March 31, 2026

Added: Preview Data endpoint

New endpoint for previewing extracted data before committing to a full load.

POST /api/v3/extract-template/{template_id}/preview/

March 27, 2026

Added: Date range parameters to Run Load endpoint

Added optional date_from and date_to request body parameters to PUT /api/v3/loads/{id}/run
Allows running a load for a specific date range instead of the default schedule window

March 12, 2026

Added: sync_historical_data field to Extract responses

New read-only field sync_historical_data (nullable ISO date string) added to Extract detail and list response schemas
Indicates when the extract last synced historical data

Affected endpoints: GET /api/v3/extracts/{id}, GET /api/v3/extracts/

January 13, 2026

Added: Automated Recipes endpoints

New endpoints for managing automated recipe execution:

Create, read, update, and delete automated recipes
Configure recipe triggers and scheduling
Monitor recipe execution status

November 20, 2025

Added: Data source category field

New category field added to the GET /api/v3/datasources response
Allows filtering and grouping data sources by their category

July 28, 2025

Added: Extract Partial Update endpoint

New PATCH endpoint for partially updating extract configurations
Allows modifying individual fields without sending the full extract payload

July 7, 2025

Added: DTS Session Authentication

New authentication flow using DTS session tokens
Alternative to API key authentication for embedded use cases

March 27, 2025

Added: DataTable detail endpoint

New GET /api/v3/data-tables/{id} endpoint for retrieving detailed information about a specific data table

Added: format, user_type and is_dynamic on field objects

Each entry of a fields list gained three attributes, in extraction template, extract and data table responses alike.

format — how the value is meant to be rendered: string, float, integer, iso_8601_date, currency, percent, duration, url or image_url. A hint, not a storage contract: metrics fall back to float when a data source declares no format explicitly, and no decimal precision is guaranteed.
user_type — broad data type of the field
is_dynamic — whether the field comes from a dynamic, per-connection schema

March 18, 2025

Added: sql_name to Extract Template detail

New sql_name field added to the extract template detail response
Useful for referencing templates in SQL-based workflows

August 30, 2024

Added: Recipes endpoints

New set of endpoints for managing data transformation recipes:

List, create, read, update, and delete recipes
Manage recipe steps and transformations
Activate and deactivate recipes

June 20, 2024

Initial release: Embedded API v3

The first public release of the Improvado Embedded API v3 specification, including:

Authentication: API key-based authentication
Data Sources: List available data sources and their configurations
Extracts: Full CRUD for data extraction configurations
Extract Templates: Browse and use pre-built extraction templates
Loads: Configure and manage data loading to destinations
Destinations: List available destination connections
Data Tables: Access workspace data tables

Last modified on August 19, 2026