Schemas

Workspace

Workspace object

id

integer

Workspace ID

title

string

Workspace title

PaginatedWorkspaceList

count

integer

Number of workspaces

next

string

URL to the next page

previous

string

URL to the previous page

Workspace[]

Recipe

Recipe object

id

integer

Recipe ID

title

string

Recipe title

Dashboard

Dashboard object

dashboard_id

string

Dashboard ID

title

string

Dashboard title

data_name

string

Dashboard Data Type

DataSource

Data source object

name

string

string identifier of datasource

title

string

Data source title

object

categories

string[]

List of categories that the data source belongs to

PaginatedDataSourceList

count

integer

Number of datasources

next

string

URL to the next page

previous

string

URL to the previous page

DataSource[]

Connection

Connection object

id

integer

Connection ID

uid

string

Connection UID

title

string

Connection title

datasource_name

string

Data source name

status

string

Connection status

created_at

string

Connection creation date

updated_at

string

Connection update date

accounts_number

integer

Total number of accounts available on this connection (excluding accounts disabled on the data source side).

enabled_for_extraction_accounts_number

integer

Number of accounts on this connection that are selected for extraction. Use this to detect connections that have no accounts enabled and prompt the user to select at least one before setting up extractions or loads.

accounts_status

string

Accounts status

update_accounts_last_successed

string

Last successful accounts update date

update_accounts_was_successfull

boolean

Was the last accounts update successful

PaginatedConnectionsList

connection list

count

integer

Number of connections

next

string

URL to the next page

previous

string

URL to the previous page

Connection[]

Account

Account object

id

integer

Account ID

account_id

string

Remote account ID

title

string

Account title

currency

string

Account currency

connection_id

integer

Connection ID

datasource_name

string

Data source name

created_at

string

Account creation date

updated_at

string

Account update date

is_active

boolean

Is the account active

enabled_for_embedded_extraction

boolean

Is the account enabled for embedded extraction

object

Data source-specific account item information

PaginatedAccountList

count

integer

Number of accounts

next

string

URL to the next page

previous

string

URL to the previous page

Account[]

ExtractTemplateCreateRequest

Request body for creating a custom extraction template

parent_id

integer · required

ID of the parent (global) extraction template to base this template on

title

string · minLength: 1 · required

Title for the new template (must be unique within the agency)

description

string · required

Description of the template (can be empty)

fields

string[] · required

List of field names to include in the template

Scheduling[] · required

Extraction schedule configuration

additional_params

object · required

Additional parameters for the template (e.g. time_granularity)

hashed_fields

string[]

List of field names to hash (optional)

Default: []

historical_data_depth_limit

integer | null

Limit on historical data depth in days (optional, null for no limit)

Default: null

connection_id

integer | null

Connection ID, required for wide report templates (parent has allow_to_select_dimensions or is_created_from_wide)

Default: null

ExtractTemplate

Extract Template object

id

integer

Extract Template ID

title

string

Extract Template title

description

string

Extract Template description

data_class

string

Data class

datasource_name

string

Data source name

schedules_limit

integer

Schedules limit

Scheduling[]

Field[]

AdditionalParams[]

PaginatedExtractTemplateList

count

integer

Number of extract templates

next

string

URL to the next page

previous

string

URL to the previous page

object[]

Scheduling

Scheduling object

days

integer · min: 0

Day offset within the interval, starting from 0. The valid range depends on interval:

hour, day — must be 0
week — 0–6 (day of week)
month — 0–30 (day of month)

hours

integer · min: 0 · max: 23

Hour at which the run will start (0–23)

minutes

integer · min: 0 · max: 59

Minute of hour at which the run will start (0–59)

interval

string · enum

Frequency at which the run will be performed:

hour — every hour
day — once per day
week — once per week
month — once per month

Enum values:

hour

day

week

month

timezone

string

IANA timezone name (e.g. UTC, America/New_York) the schedule is interpreted in.

Default: UTC

recurrence

integer

How often the schedule repeats within the interval. Defaults to 1.

Default: 1

object

Defines the period data will be extracted for. Applies to extract schedules only — ignored for load schedules.

Field

Field object

title

string

Field title

name

string

Field name

user_kind

string

Field kind

user_type

string

Field type

selected

boolean

Is the field selected

can_edit

boolean

Can the field be edited

sql_name

string

Sql Name of a Field

format

string

Field format

is_dynamic

boolean

Is the field dynamic

AdditionalParams

Additional Params object

type

string

Additional Params type

name

string

Additional Params name

required

boolean

Is the Additional Params required

title

string

Additional Params title

description

string

Additional Params description

params

object

Additional Params params

initial_value

string

Additional Params initial value

Extract

Extract object

id

integer

Extract ID

title

string

Extract title

connection_id

integer

Connection ID

account_id

integer

Account ID

account_name

string

Account name

object

Field[]

created_at

string

Extract creation date

last_sync

string

Last sync date

status

string

Extract status

error_text

string

Error text

schedules_limit

integer

Schedules limit

Scheduling[]

AdditionalParams[]

sync_historical_data

string | null · readOnly

Start date for historical data backfill (ISO date format, e.g. "2025-02-25"). Null if not set.

PaginatedExtractList

count

integer

Number of extracts

next

string

URL to the next page

previous

string

URL to the previous page

object[]

Destination

Destination object

name

string

string identifier of destination

title

string

Destination title

info

string

Destination info

object

PaginatedDestinationList

count

integer

Number of destinations

next

string

URL to the next page

previous

string

URL to the previous page

Destination[]

DestinationConnection

Destination Connection object

id

integer

Destination Connection ID

Destination

Destination object

Example: {"destination":{"value":{"name":"google_sheets","title":"Google Sheets","info":"Google Sheets destination","icons":{"res_300x200":"https://example.com/icon_300x200.png","res_40x40":"https://example.com/icon_40x40.png","res_20x20":"https://example.com/icon_20x20.png"}}}}

title

string

Destination Connection title

updated_at

string

Destination Connection update date

status

string

Destination Connection status

error_text

string

Destination Connection error text

is_editable

boolean

Is the Destination Connection editable

create_load_for_new_tables

boolean

Create load for new tables

PaginatedDestinationConnectionList

count

integer

Number of destination connections

next

string

URL to the next page

previous

string

URL to the previous page

DestinationConnection[]

DataTable

Data Table object

id

integer

Data Table ID

title

string

Data Table title

datasource_name

string

Data source name

TableField

Table Field object

kind

string

Field kind

title

string

Field title

sql_name

string

SQL name

field_type

string

Field type

format

string

Field format

is_dynamic

boolean

Is the field dynamic

is_selected

boolean

Is the field selected

DataTableDetail

Data Table Detail object

title

string

Data Table title

freshness

string

Data Table freshness date

datasource_name

string

Data source name

report_type

string

Report type

data_class

string

Data class

workspace

integer

Workspace ID

sql_name

string

SQL name

auto_extract_new_accounts

boolean

Auto extract new accounts

object

Fields object

PaginatedDataTableList

count

integer

Number of data tables

next

string

URL to the next page

previous

string

URL to the previous page

DataTable[]

Load

Load object

id

integer

Load ID

DataTable

Data Table object

Example: {"data_table":{"value":{"id":1,"title":"Table 1","datasource_name":"google_sheets"}}}

object

destination_table

string

Destination table name

run_policy

string · enum

Load run policy

Enum values:

after extraction

schedule

Scheduling[]

status

string

Load status

last_update

string

Last update date

error_text

string

Error text

uploaded_rows_count

integer

Number of uploaded rows

PaginatedLoadList

count

integer

Number of loads

next

string

URL to the next page

previous

string

URL to the previous page

Load[]

List of Loads

ExtractTemplatePreviewRequest

Request payload for extraction template data preview.

connection_id

integer

Connection ID to use for the preview.

Example: 52955

object

Custom settings for the extraction.

Example: {"time_granularity":"week","week_start_day":"monday","sync_historical_data":"2025-09-27","lookback_window":"default","custom_refresh_window":1,"pivot":"COMPANY"}

fields

string[]

List of fields to include in the preview.

Example: ["date","input:pivot","pivotValues","approximateMemberReach"]

dynamic_fields

string[]

List of dynamic fields to include.

Example: []

accounts

string[]

List of account IDs.

Example: ["507446188"]

custom_filters

Custom filters to apply. Null if no filters.

Example: null

ExtractTemplatePreviewResponse

Response containing preview data for an extraction template.

object

CustomSettingOptionsRequest

Request payload for loading dynamic custom setting options.

template_id

integer · required

Extraction template ID whose custom setting is being resolved.

Example: 10430

connection_id

integer · required

Connection ID used to resolve credentials and scope accounts.

Example: 20595

account_ids

string[] · minItems: 1 · required

Remote account IDs from the source platform, scoped by connection_id. These are the same string account IDs used by extraction template preview.

Example: ["47924620"]

custom_setting_name

string · required

Custom setting name from the extraction template.

Example: form_guids

search_query

string

Optional case-insensitive search query applied to loaded options.

Example: contact

Default:

page

integer · min: 1

Page number for paginated options.

Example: 1

Default: 1

page_size

integer · min: 1 · max: 1000

Number of options to return per account.

Example: 50

Default: 50

CustomSettingOption

A single selectable custom setting option.

value

string

Value that should be submitted as the custom setting value.

Example: 801130ad-d745-450a-a974-741b704cbd58

label

string

Human-readable option label.

Example: New contact us form

description

string | null

Optional extra text that can be shown in the UI.

Example: HUBSPOT

CustomSettingOptionsAccountResult

Custom setting options resolved for one account. Pagination follows the standard paginated-response shape (`count`, `next`, `previous`, `results`). Search is applied locally over the cached entity-report options before pagination.

account_id

string

Remote account ID from the request.

Example: 47924620

count

integer

Total number of options after the search filter is applied.

Example: 1

next

string | null

Next page number as a string, or null if this is the last page.

Example: null

previous

string | null

Previous page number as a string, or null if this is the first page.

Example: null

CustomSettingOption[]

Page of selectable options for this account.

search_applied

boolean

Whether a non-empty search query was applied.

Example: true

CustomSettingOptionsResponse

Response containing dynamic custom setting options per account.

custom_setting_name

string

Custom setting name from the request.

Example: form_guids

CustomSettingOptionsAccountResult[]

Role

Workspace role (system or agency-custom).

id

integer · required

Role ID

title

string · required

Role title (unique within the agency)

description

string · required

Optional human-readable description

is_system

boolean · required

True for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.

is_internal

boolean · required

True for internal-only roles (impersonation, guest viewers). These are never listed in the API.

object · required

Permissions grouped by product layer. Layer codes match code in the permissions catalog.

user_count

integer · required

Number of users currently assigned to this role across the agency.

RoleListResponse

Role[] · required

RoleWriteRequest

Payload for creating or updating a custom role.

title

string · required

Role title. Must be non-empty and unique within the agency.

object · required

Permissions grouped by product layer. Use codes from GET /api/v3/roles/permissions.

description

string

Optional description.

CreateRoleResponse

id

integer · required

ID of the newly created role.

DeleteRoleResponse

reassigned_users_count

integer · required

Number of users that were reassigned to the Viewer system role as part of the delete.

CatalogPermission

code

string · required

Permission code (stable identifier, e.g. view, create, manage_roles).

title

string · required

Human-readable title.

description

string · required

Longer description suitable for tooltips.

CatalogLayer

code

string · required

Product layer code (stable identifier, e.g. extract, admin).

title

string · required

Human-readable layer name.

description

string · required

Layer description suitable for headers/tooltips.

CatalogPermission[] · required

PermissionsCatalogResponse

CatalogLayer[] · required

Ordered list of product layers with their valid permissions.

RoleUser

user_id

integer · required

name

string · required

Display name. Falls back to email if first/last name are blank.

email

string · required

workspace_id

integer · required

workspace_title

string · required

RoleUsersResponse

RoleUser[] · required

ErrorResponse

Error response object

detail

string

Error message

AutomatedRecipeTemplateDataSource

Data source reference in automated recipe template

name

string

Data source identifier

title

string

Data source display name

AutomatedRecipeTemplate

Automated recipe template object

id

integer

Template ID

title

string

Template title

description

string

Template description

AutomatedRecipeTemplateDataSource[]

List of data sources used by this template

created_at

string · date-time

Template creation timestamp

updated_at

string · date-time

Template last update timestamp

PaginatedAutomatedRecipeTemplateList

Paginated list of automated recipe templates

count

integer

Total number of templates

next

string | null

URL to the next page

previous

string | null

URL to the previous page

AutomatedRecipeTemplate[]

AutomatedRecipeTemplateTreeNode

Node in the template dependency tree

id

integer

Node ID

title

string

Node title

level

integer

Depth level in the tree (0 = root)

parent_id

integer

Parent node ID (absent for root)

AutomatedRecipeTemplateTreeStructure

Tree structure showing template dependencies

AutomatedRecipeTemplateTreeNode

Node in the template dependency tree

AutomatedRecipeTemplateTreeNode[]

AutomatedRecipeTemplateDetail

Detailed automated recipe template with tree structure

id

integer

Template ID

title

string

Template title

description

string

Template description

AutomatedRecipeTemplateDataSource[]

List of data sources used by this template

AutomatedRecipeTemplateTreeStructure

Tree structure showing template dependencies

dependencies_count

integer

Number of dependencies in the template

created_at

string · date-time

Template creation timestamp

updated_at

string · date-time

Template last update timestamp

AutomatedRecipe

Automated recipe object

recipe_id

string

Unique recipe identifier (numeric string)

template_id

integer

ID of the template this recipe was created from

template_title

string

Title of the source template

title

string

Recipe title

state

string · enum

Current recipe state

Enum values:

Extracting Data

Building Dependencies

Ready To Work

Failed

workspace_id

integer

Workspace ID

created_at

string · date-time

Recipe creation timestamp

updated_at

string · date-time

Recipe last update timestamp

PaginatedAutomatedRecipeList

Paginated list of automated recipes

count

integer

Total number of recipes

next

string | null

URL to the next page

previous

string | null

URL to the previous page

AutomatedRecipe[]

AutomatedRecipeCreateResponse

Response after creating an automated recipe

recipe_id

string

Unique recipe identifier (numeric string)

template_id

integer

ID of the template this recipe was created from

title

string

Recipe title

state

string · enum

Initial recipe state (typically "Extracting Data")

Enum values:

Extracting Data

Building Dependencies

Ready To Work

Failed

AutomatedRecipeConnectionAccount

Account within a connection

id

integer

Account ID

account_id

string

External account identifier

AutomatedRecipeConnection

Connection configuration for automated recipe

connection_id

integer

Connection ID

connection_data_source

string

Data source name for this connection

AutomatedRecipeConnectionAccount[]

List of accounts for this connection

AutomatedRecipeDetail

Detailed automated recipe with full configuration

recipe_id

string

Unique recipe identifier (numeric string)

template_id

integer

ID of the template this recipe was created from

datatable_id

integer | null

Associated data table ID (null if not yet created)

title

string

Recipe title

state

string · enum

Current recipe state

Enum values:

Extracting Data

Building Dependencies

Ready To Work

Failed

data_sources

string[]

List of configured data source names

allowed_data_sources

string[]

List of allowed data source names for this recipe

AutomatedRecipeConnection[]

List of configured connections

sync_from_date

string · date

Start date for data synchronization

last_build_at

string · date-time

Last successful build timestamp

created_at

string · date-time

Recipe creation timestamp

updated_at

string · date-time

Recipe last update timestamp

AutomatedRecipeUpdateRequest

Request body for updating automated recipe configuration

data_sources

string[] · required

List of data source names to include

AutomatedRecipeConnection[] · required

List of connections with accounts

sync_from_date

string · date

Start date for data synchronization (YYYY-MM-DD)

AutomatedRecipeBuildResponse

Response from build operation

status

string · enum

Build operation status

Enum values:

building

error

message

string

Human-readable status message

WebhookSubscription

A subscription that links a webhook endpoint to a specific event type.

id

integer

Subscription ID

event_type_name

string

Name of the event type this subscription receives

is_active

boolean

Whether the subscription is active

created_at

string · date-time

When the subscription was created

WebhookEndpointListItem

Compact webhook endpoint representation used in list responses.

id

integer

Webhook endpoint ID

url

string · uri

Receiver URL

status

string · enum

Endpoint lifecycle status. unverified endpoints do not receive event deliveries.

Enum values:

unverified

active

consecutive_failures

integer

Number of consecutive failed deliveries since the last successful delivery

subscriptions_count

integer

Number of event types this endpoint is subscribed to

created_at

string · date-time

updated_at

string · date-time

WebhookEndpointDetail

Full webhook endpoint representation, including the signing secret and the list of subscriptions. The `secret` is used to compute the `X-Improvado-Signature` header (HMAC-SHA256) on every event delivery and as the verification token during the verify flow. Treat it as sensitive and store it securely.

id

integer

url

string · uri

secret

string

64-character hex signing secret

status

string · enum

Enum values:

unverified

active

consecutive_failures

integer

WebhookSubscription[]

created_at

string · date-time

updated_at

string · date-time

PaginatedWebhookEndpointList

count

integer

next

string | null

previous

string | null

WebhookEndpointListItem[]

WebhookEndpointCreateRequest

url

string · uri · maxLength: 2048 · required

HTTPS URL of the receiver that will accept event deliveries.

event_types

string[]

Event types this endpoint will subscribe to. See GET /api/v3/webhook_event_types/ for the list of available event names. Duplicates are deduplicated server-side. May be empty.

WebhookEndpointUpdateRequest

Partial update payload. Either field may be omitted. Setting `event_types` replaces the full set of subscriptions for the endpoint. Updating either field resets the endpoint to `unverified`.

url

string · uri · maxLength: 2048

event_types

string[]

WebhookEventType

An event type that can be subscribed to.

event_name

string

Identifier of the event type (used in event_types when creating subscriptions)