Improvado Embedded API v3

Extraction templates

Endpointhttps://embedded.improvado.io

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.

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

object[]

count

integer

Number of extract templates

next

string

URL to the next page

previous

string

URL to the previous page

object[]

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

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

shell

Example Responses

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "title": "Extract Template 1",
      "description": "Extract Template 1 description",
      "data_class": "table",
      "labels": [
        {
          "color": "magenta",
          "name": "Label 1"
        }
      ],
      "datasource_name": "google_sheets"
    },
    {
      "id": 2,
      "title": "Extract Template 2",
      "description": "Extract Template 2 description",
      "data_class": "table",
      "labels": [
        {
          "color": "magenta",
          "name": "Label 1"
        }
      ],
      "datasource_name": "google_ads"
    }
  ]
}

json

application/json

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

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

object[] · 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

object[]

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

object[]

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.

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

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

object[]

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

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

object[] · 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

object[]

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

object[]

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.

object