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

Destination connections are created and modified through the iframe UI to securely handle credentials.

List destination connections

GET

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections

List destination connections

List destination connections › path Parameters

destination_name

string · required

Destination name

List destination connections › Responses

List of destination connections

PaginatedDestinationConnectionList[]

PaginatedDestinationConnectionList

count

integer

Number of destination connections

next

string

URL to the next page

previous

string

URL to the previous page

DestinationConnection[]

GET/api/v3/destinations/{destination_name}/connections

curl --request GET \
  --url https://embedded.improvado.io/api/v3/destinations/:destination_name/connections

shell

Example Responses

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "destination": {
        "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": "Destination Connection 1",
      "updated_at": "2021-01-01T00:00:00Z",
      "status": "active",
      "error_text": "Error text",
      "is_editable": true,
      "create_load_for_new_tables": true
    },
    {
      "id": 2,
      "destination": {
        "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": "Destination Connection 1",
      "updated_at": "2021-01-01T00:00:00Z",
      "status": "active",
      "error_text": "Error text",
      "is_editable": true,
      "create_load_for_new_tables": true
    }
  ]
}

json

application/json

Create a connection

POST

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections

Create a destination connection of a given type

Create a connection › path Parameters

destination_name

string · required

Destination name

Create a connection › Request Body

title

string

Connection title

create_load_for_new_tables

boolean

Create load for new tables

destination_name

string

Destination name

conenctions_params

object

Connection params

Create a connection › Responses

Create a Connection

No data returned

POST/api/v3/destinations/{destination_name}/connections

curl --request POST \
  --url https://embedded.improvado.io/api/v3/destinations/:destination_name/connections \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Destination Connection 1",
  "create_load_for_new_tables": true,
  "destination_name": "s3",
  "conenctions_params": {
    "aws_access_key_id": "test",
    "aws_secret_access_key": "test",
    "aws_default_region": "eu-west-1",
    "bucket_name": "test-bucket",
    "folder": "test-folder",
    "filename": "{{ filename }}-{{ YYYY }}-{{ MM }}-{{ DD }}",
    "file_format": "parquet",
    "separator": ",",
    "partition_by": "by_day",
    "encryption": "sse_s3",
    "encryption_key": "stub",
    "use_load_by_accounts": false
  }
}
'

shell

Example Request Body

{
  "title": "Destination Connection 1",
  "create_load_for_new_tables": true,
  "destination_name": "s3",
  "conenctions_params": {
    "aws_access_key_id": "test",
    "aws_secret_access_key": "test",
    "aws_default_region": "eu-west-1",
    "bucket_name": "test-bucket",
    "folder": "test-folder",
    "filename": "{{ filename }}-{{ YYYY }}-{{ MM }}-{{ DD }}",
    "file_format": "parquet",
    "separator": ",",
    "partition_by": "by_day",
    "encryption": "sse_s3",
    "encryption_key": "stub",
    "use_load_by_accounts": false
  }
}

json

application/json

Example Responses

No example specified for this content type

Get a connection

GET

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{id}

Get detailed info about destination connection

Get a connection › path Parameters

destination_name

string · required

Destination name

id

integer · required

Destination Connection ID

Get a connection › Responses

Get a Connection

Connection object

Connection

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

GET/api/v3/destinations/{destination_name}/connections/{id}

curl --request GET \
  --url https://embedded.improvado.io/api/v3/destinations/:destination_name/connections/:id

shell

Example Responses

{
  "id": 1,
  "destination": {
    "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": "Destination Connection 1",
  "updated_at": "2021-01-01T00:00:00Z",
  "status": "active",
  "error_text": "Error text",
  "is_editable": true,
  "create_load_for_new_tables": true
}

json

application/json

Reauthorize a connection

PUT

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{id}

Reauthorize an existing destination connection

Reauthorize a connection › path Parameters

destination_name

string · required

Destination name

id

integer · required

Destination Connection ID

Reauthorize a connection › Request Body

title

string

Connection title

connection_params

object

Connection params

Reauthorize a connection › Responses

Reauthorize a Connection

No data returned

PUT/api/v3/destinations/{destination_name}/connections/{id}

curl --request PUT \
  --url https://embedded.improvado.io/api/v3/destinations/:destination_name/connections/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "title": "Destination Connection 1",
  "connection_params": {
    "aws_access_key_id": "test",
    "aws_secret_access_key": "test",
    "aws_default_region": "eu-west-1",
    "bucket_name": "test-bucket",
    "folder": "test-folder",
    "filename": "{{ filename }}-{{ YYYY }}-{{ MM }}-{{ DD }}",
    "file_format": "parquet",
    "separator": ",",
    "partition_by": "by_day",
    "encryption": "sse_s3",
    "encryption_key": "stub",
    "use_load_by_accounts": false
  }
}
'

shell

Example Request Body

{
  "title": "Destination Connection 1",
  "connection_params": {
    "aws_access_key_id": "test",
    "aws_secret_access_key": "test",
    "aws_default_region": "eu-west-1",
    "bucket_name": "test-bucket",
    "folder": "test-folder",
    "filename": "{{ filename }}-{{ YYYY }}-{{ MM }}-{{ DD }}",
    "file_format": "parquet",
    "separator": ",",
    "partition_by": "by_day",
    "encryption": "sse_s3",
    "encryption_key": "stub",
    "use_load_by_accounts": false
  }
}

json

application/json

Example Responses

No example specified for this content type

Update a connection

PATCH

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{id}

Allows to update create_load_for_new_tables value for destination connection

Update a connection › path Parameters

destination_name

string · required

Destination name

id

integer · required

Destination Connection ID

Update a connection › Request Body

create_load_for_new_tables

boolean

Update a connection › Responses

Update a Connection

Destination Connection object

DestinationConnection

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

PATCH/api/v3/destinations/{destination_name}/connections/{id}

curl --request PATCH \
  --url https://embedded.improvado.io/api/v3/destinations/:destination_name/connections/:id \
  --header 'Content-Type: application/json' \
  --data '
{
  "create_load_for_new_tables": true
}
'

shell

Example Request Body

{
  "create_load_for_new_tables": true
}

json

application/json

Example Responses

{
  "id": 1,
  "destination": {
    "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": "Destination Connection 1",
  "updated_at": "2021-01-01T00:00:00Z",
  "status": "active",
  "error_text": "Error text",
  "is_editable": true,
  "create_load_for_new_tables": true
}

json

application/json

Check connection status

PUT

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{destination_connection_id}/recheck

Starts a manual status check of a destination connection. If a destination connection has invalid or staled connection credentials – the system will mark this destination connection as invalid for future loads.

Check connection status › path Parameters

destination_name

string · required

Destination name

destination_connection_id

integer · required

Destination Connection ID

Check connection status › Responses

Recheck a Connection

No data returned

Destinations Loads

List destination connections

GET

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections

List destination connections

List destination connections › path Parameters

destination_name

string · required

Destination name

List destination connections › Responses

List of destination connections

PaginatedDestinationConnectionList[]

PaginatedDestinationConnectionList

count

integer

Number of destination connections

next

string

URL to the next page

previous

string

URL to the previous page

DestinationConnection[]

Create a connection

POST

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections

Create a destination connection of a given type

Create a connection › path Parameters

destination_name

string · required

Destination name

Create a connection › Request Body

title

string

Connection title

create_load_for_new_tables

boolean

Create load for new tables

destination_name

string

Destination name

conenctions_params

object

Connection params

Create a connection › Responses

Create a Connection

No data returned

Get a connection

GET

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{id}

Get detailed info about destination connection

Get a connection › path Parameters

destination_name

string · required

Destination name

id

integer · required

Destination Connection ID

Get a connection › Responses

Get a Connection

Connection object

Connection

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

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

Reauthorize a connection

PUT

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{id}

Reauthorize an existing destination connection

Reauthorize a connection › path Parameters

destination_name

string · required

Destination name

id

integer · required

Destination Connection ID

Reauthorize a connection › Request Body

title

string

Connection title

connection_params

object

Connection params

Reauthorize a connection › Responses

Reauthorize a Connection

No data returned

Update a connection

PATCH

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{id}

Allows to update create_load_for_new_tables value for destination connection

Update a connection › path Parameters

destination_name

string · required

Destination name

id

integer · required

Destination Connection ID

Update a connection › Request Body

create_load_for_new_tables

boolean

Update a connection › Responses

Update a Connection

Destination Connection object

DestinationConnection

id

integer

Destination Connection ID

Destination

Destination object

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

Check connection status

PUT

https://embedded.improvado.io

/api/v3/destinations/{destination_name}/connections/{destination_connection_id}/recheck

Check connection status › path Parameters

destination_name

string · required

Destination name

destination_connection_id

integer · required

Destination Connection ID

Check connection status › Responses

Recheck a Connection

No data returned