Extraction templates

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

POST/api/v3/datasources/{datasource_name}/extract-templates

curl --request POST \
  --url https://embedded.improvado.io/api/v3/datasources/:datasource_name/extract-templates \
  --header 'Content-Type: application/json' \
  --data '
{
  "parent_id": 123,
  "title": "My Custom Template",
  "description": "Custom template for daily extraction",
  "fields": [
    "impressions",
    "clicks",
    "spend"
  ],
  "scheduling": [
    {
      "hours": 6,
      "minutes": 0,
      "timezone": "UTC",
      "interval": "day",
      "lookback_window": {
        "name": "default"
      }
    }
  ],
  "additional_params": {}
}
'

shell

Example Request Body

{
  "parent_id": 123,
  "title": "My Custom Template",
  "description": "Custom template for daily extraction",
  "fields": [
    "impressions",
    "clicks",
    "spend"
  ],
  "scheduling": [
    {
      "hours": 6,
      "minutes": 0,
      "timezone": "UTC",
      "interval": "day",
      "lookback_window": {
        "name": "default"
      }
    }
  ],
  "additional_params": {}
}

json

application/json

Example Responses

{
  "id": 100,
  "title": "My Custom Template",
  "description": "Custom template for daily extraction",
  "data_class": "daily",
  "datasource_name": "act_on",
  "schedules_limit": 1,
  "scheduling": [
    {
      "hours": 6,
      "minutes": 0,
      "timezone": "UTC",
      "interval": "day",
      "lookback_window": {
        "name": "default"
      }
    }
  ],
  "fields": [
    {
      "title": "Impressions",
      "name": "impressions",
      "user_kind": "metric",
      "user_type": "integer",
      "selected": true,
      "can_edit": true,
      "sql_name": "impressions",
      "format": "integer",
      "is_dynamic": false
    }
  ],
  "additional_params": []
}

json

application/json

Get an extraction template

GET

https://embedded.improvado.io

/api/v3/datasources/{datasource_name}/extract-templates/{id}

Returns detailed info about extraction template

Get an extraction template › path Parameters

datasource_name

string · required

Datasource name

id

integer · required

Extract Template ID

Get an extraction template › Responses

Get an extraction template

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

ExtractTemplatePreviewRequest

GET/api/v3/datasources/{datasource_name}/extract-templates/{id}

curl --request GET \
  --url https://embedded.improvado.io/api/v3/datasources/:datasource_name/extract-templates/:id

shell

Example Responses

{
  "id": 1,
  "title": "Extract Template 1",
  "description": "Extract Template 1 description",
  "data_class": "table",
  "datasource_name": "google_sheets",
  "schedules_limit": 1,
  "scheduling": [
    {
      "days": 1,
      "hours": 1,
      "minutes": 1,
      "interval": "daily",
      "timezone": "UTC",
      "lookback_window": {
        "name": "1 day"
      }
    }
  ],
  "fields": [
    {
      "title": "Field 1",
      "name": "field_1",
      "user_kind": "dimension",
      "user_type": "string",
      "selected": true,
      "can_edit": true,
      "format": "string",
      "is_dynamic": false,
      "sql_name": "field_1_sql"
    }
  ],
  "additional_params": [
    {
      "type": "string",
      "name": "param_1",
      "required": true,
      "title": "Param 1",
      "description": "Param 1 description",
      "params": {},
      "initial_value": "value"
    }
  ]
}

json

application/json

Preview extraction template data

POST

https://embedded.improvado.io

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

Returns a preview of data that would be extracted using the given template configuration. The response includes both the data rows and column metadata.

Preview extraction template data › path Parameters

template_id

integer · required

A unique integer value identifying this Extraction template.

Preview extraction template data › Request Body

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

Preview extraction template data › Responses

Preview data with rows and column metadata

Response containing preview data for an extraction template.

ExtractTemplatePreviewResponse

object

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

curl --request POST \
  --url https://embedded.improvado.io/api/v3/extract-template/:template_id/preview/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "connection_id": 52955,
  "custom_settings": {
    "time_granularity": "week",
    "week_start_day": "monday",
    "sync_historical_data": "2025-09-27",
    "lookback_window": "default",
    "custom_refresh_window": 1,
    "pivot": "COMPANY"
  },
  "fields": [
    "date",
    "input:pivot",
    "pivotValues",
    "approximateMemberReach"
  ],
  "dynamic_fields": [],
  "accounts": [
    "507446188"
  ],
  "custom_filters": null
}
'

shell

Example Request Body

{
  "connection_id": 52955,
  "custom_settings": {
    "time_granularity": "week",
    "week_start_day": "monday",
    "sync_historical_data": "2025-09-27",
    "lookback_window": "default",
    "custom_refresh_window": 1,
    "pivot": "COMPANY"
  },
  "fields": [
    "date",
    "input:pivot",
    "pivotValues",
    "approximateMemberReach"
  ],
  "dynamic_fields": [],
  "accounts": [
    "507446188"
  ],
  "custom_filters": null
}

json

application/json

Example Responses

{
  "data": {
    "dataSource": [
      {
        "key": "1",
        "date": "2025-11-20",
        "__account_id": "12341234",
        "__insert_date": "2026-03-18T05:34:00",
        "advertiser": "dafasdf",
        "advertiser_id": "95123412390291",
        "campaign": "asdfasdf",
        "campaign_end_date": "2024-10-10",
        "campaign_id": "23123412481",
        "campaign_start_date": "2019-10-10",
        "placement": "asdfasdf",
        "placement_id": "267085055",
        "site": "asdfasdf",
        "site_id": "53866asdfasdf27",
        "unique_reach_total_reach": 0,
        "account_name": "asdfasd.asdfasd",
        "date_yyyymmdd": "20251120"
      }
    ],
    "columns": [
      {
        "title": "Date",
        "dataIndex": "date",
        "key": "date"
      },
      {
        "title": "  account id",
        "dataIndex": "__account_id",
        "key": "__account_id"
      },
      {
        "title": "  insert date",
        "dataIndex": "__insert_date",
        "key": "__insert_date"
      }
    ]
  }
}

json

application/json

Load custom setting options

POST

https://embedded.improvado.io

/api/v3/datasources/{datasource_name}/custom_setting_options/

Returns selectable options for a custom extraction setting that is backed by source entities. Use this endpoint when an extraction template exposes a select custom setting with dynamic source metadata and the UI needs to populate its choices for one or more accounts. Account IDs in the request are remote account IDs from the source platform (the same string IDs used by extraction template preview), scoped by the provided connection_id. Search and pagination are applied over the loaded option list by Improvado, so source APIs do not need to support filtering or paging.

Load custom setting options › path Parameters

datasource_name

string · required

Data source name.

Load custom setting options › Request Body

Request payload for loading dynamic custom setting options.

CustomSettingOptionsRequest

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

Load custom setting options › Responses

Custom setting options grouped by account.

Response containing dynamic custom setting options per account.

CustomSettingOptionsResponse

custom_setting_name

string

Custom setting name from the request.

Example: form_guids

CustomSettingOptionsAccountResult[]

POST/api/v3/datasources/{datasource_name}/custom_setting_options/

curl --request POST \
  --url https://embedded.improvado.io/api/v3/datasources/:datasource_name/custom_setting_options/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "template_id": 10430,
  "connection_id": 20595,
  "account_ids": [
    "47924620"
  ],
  "custom_setting_name": "form_guids",
  "search_query": "contact",
  "page": 1,
  "page_size": 50
}
'

shell

Example Request Body

{
  "template_id": 10430,
  "connection_id": 20595,
  "account_ids": [
    "47924620"
  ],
  "custom_setting_name": "form_guids",
  "search_query": "contact",
  "page": 1,
  "page_size": 50
}

json

application/json

Example Responses

{
  "custom_setting_name": "form_guids",
  "results": [
    {
      "account_id": "47924620",
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
        {
          "value": "801130ad-d745-450a-a974-741b704cbd58",
          "label": "New contact us form",
          "description": "HUBSPOT"
        }
      ],
      "search_applied": true
    }
  ]
}

json

application/json

Accounts Extracts

List extraction templates for a datasource

GET

https://embedded.improvado.io

/api/v3/datasources/{datasource_name}/extract-templates

List extraction templates available for datasource

List extraction templates for a datasource › path Parameters

datasource_name

string · required

Datasource name

List extraction templates for a datasource › Responses

Get a list of extraction templates

PaginatedExtractTemplateList[]

PaginatedExtractTemplateList

count

integer

Number of extract templates

next

string

URL to the next page

previous

string

URL to the previous page

object[]

Create an extraction template

POST

https://embedded.improvado.io

/api/v3/datasources/{datasource_name}/extract-templates

Create a custom (agency-level) extraction template based on a parent global template.

For wide report templates (parent has allow_to_select_dimensions or is_created_from_wide), a connection_id is required and the selected fields are validated against the DSAS API.

Required RBAC permission: EXTRACT.CREATE.

Create an extraction template › path Parameters

datasource_name

string · required

Datasource name

Create an extraction template › Request Body

Request body for creating a custom extraction template

ExtractTemplateCreateRequest

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

Create an extraction template › Responses

Template created successfully

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

Get an extraction template

GET

https://embedded.improvado.io

/api/v3/datasources/{datasource_name}/extract-templates/{id}

Returns detailed info about extraction template

Get an extraction template › path Parameters

datasource_name

string · required

Datasource name

id

integer · required

Extract Template ID

Get an extraction template › Responses

Get an extraction template

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