Create a Connection

Creates a new connection within a specified group in your Fivetran account. Runs setup tests and returns testing results.

Request schema

azure_service_bus

Header parameters

Authorization

stringrequired

HTTP: basicAuth

HTTP AuthorizationScheme: basic

string

default:

application/json;version=2

example:

application/json;version=2

Request

group_id

stringrequired

The unique identifier for the group within the Fivetran system

example:

group_id

service

stringrequired

azure_service_bus

The connector name within the Fivetran system

example:

google_ads

trust_certificates

boolean

Specifies whether we should trust the certificate automatically. The default value is FALSE. If a certificate is not trusted automatically, it has to be approved with Certificates Management API Approve a destination certificate.

example:

true

trust_fingerprints

boolean

Specifies whether we should trust the SSH fingerprint automatically. The default value is FALSE. If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a destination fingerprint.

example:

true

run_setup_tests

boolean

Specifies whether the setup tests should be run automatically. The default value is TRUE.

example:

true

paused

boolean

Specifies whether the connection is paused

pause_after_trial

boolean

Specifies whether the connection should be paused after the free trial period has ended

sync_frequency

integer

The connection sync frequency in minutes

format:

int32

enum:

"1""5""15""30""60""120""180""360""480""720""1440"

data_delay_sensitivity

string

The level of data delay notification threshold. Possible values: LOW, NORMAL, HIGH, CUSTOM. The default value NORMAL. CUSTOM is only available for customers using the Enterprise plan or above.

enum:

"LOW""NORMAL""HIGH""CUSTOM"

data_delay_threshold

integer

Custom sync delay notification threshold in minutes. The default value is 0. This parameter is only used when data_delay_sensitivity set to CUSTOM.

format:

int32

daily_sync_time

string

The optional parameter that defines the sync start time when the sync frequency is already set or being set by the current request to 1440. It can be specified in one hour increments starting from 00:00 to 23:00. If not specified, we will use the baseline sync start time. This parameter has no effect on the 0 to 60 minutes offset used to determine the actual sync start time

example:

14:00

schedule_type

string

The connection schedule configuration type. Supported values: auto, manual

enum:

"auto""manual"

local_processing_agent_id

string

(Deprecated) The unique identifier for the hybrid deployment agent within the Fivetran system

example:

local_processing_agent_id

hybrid_deployment_agent_id

string

The unique identifier for the hybrid deployment agent within the Fivetran system. If not specified, the agent ID from the destination will be used

example:

hybrid_deployment_agent_id

connect_card_config

object

redirect_uri

stringrequired

The URI on your site we redirect the end user to after successful setup. The URI must start with the https or http prefix.

example:

https://your.site/path

hide_setup_guide

boolean

An optional parameter that lets you hide the embedded setup guide in the Connect Card.

example:

true

proxy_agent_id

string

The unique identifier for the proxy agent within the Fivetran system

example:

proxy_agent_id

private_link_id

string

The unique identifier for the self-served private link that is used by the connection

example:

private_link_id

networking_method

string

enum:

"Directly""PrivateLink""SshTunnel""ProxyAgent"

config

object

has_manage_permissions

boolean

The boolean value specifying whether the connection string has manage permissions

title:

has_manage_permissions

example:

true

host_ip

string

The IP address of the host machine which we use to connect to ASB via ssh

title:

host_ip

example:

string

auth_type

object

The authentication mode to access the topic

title:

auth_type

enum:

"ConnectionString""AzureActiveDirectory"

sync_type

object

The sync type, which is based on the message type. For text and xml, packed is supported. For protobuf and avro, unpacked is supported. For json, both packed and unpacked are supported

title:

sync_type

enum:

"Packed""Unpacked"

topics

array

The comma-separated list of topics which should be synced. Required if you do not have manage permissions

example:

string

type:

string

message_type

object

The format of messages in the topic

title:

message_type

enum:

"Xml""Text""Json""Avro"

connection_string

string

The connection string used for authentication. Required if the authentication type is ConnectionString

title:

connection_string

format:

password

example:

Connection String

connection_method

object

The connection method

title:

connection_method

enum:

"SSH_TUNNEL""DIRECT""PRIVATE_LINK"

namespace

string

The ASB namespace which we have to sync. Required for AzureActiveDirectory authentication.

title:

namespace

example:

my_namespace

schema_registry_secret

string

The secret used to access the schema registry. Required for the avro and protobuf message types

title:

schema_registry_secret

format:

password

example:

schema_registry_secret

subscriber_name

string

The subscriber name. If the connection string does not have manage permission, you need to specify a subscriber name we can use to fetch data. If not specified, we default to fivetran_sub_<schema>

title:

subscriber_name

example:

subscriber_name

host_user

string

The username on the host machine which we use to connect to ASB via ssh

title:

host_user

example:

string

asb_ip

string

The IP address (or) the URL of ASB namespace

title:

asb_ip

example:

string

schema_registry_key

string

The key used to access the schema registry. Required for the avro and protobuf message types

title:

schema_registry_key

example:

schema_registry_key

schema_registry_urls

array

The comma-separated list of schema registry servers in the server:port format

example:

string

type:

string

schema

string

Destination schema name. Schema name is permanent and cannot be changed after connection creation

title:

Destination schema name

example:

schema_name

auth

object

refresh_token

string

The refresh token. Required if the authentication type is AzureActiveDirectory

example:

refresh_token

client_access

object

client_secret

string

Client Secret of your Azure application. Required if the authentication type is AzureActiveDirectory

example:

my_client_secret

client_id

string

Client ID of your Azure application. Required if the authentication type is AzureActiveDirectory

example:

my_client_id

Http + 1.1

POST

https://api.fivetran.com/v1/connections

POST /v1/connections HTTP/1.1
Accept: application/json;version=2
Authorization: Basic REPLACE_BASIC_AUTH
Content-Type: application/json
Host: api.fivetran.com
Content-Length: 1547

{
  "group_id": "group_id",
  "service": "azure_service_bus",
  "trust_certificates": true,
  "trust_fingerprints": true,
  "run_setup_tests": true,
  "paused": false,
  "pause_after_trial": false,
  "sync_frequency": 1440,
  "data_delay_sensitivity": "NORMAL",
  "data_delay_threshold": 0,
  "daily_sync_time": "14:00",
  "schedule_type": "auto",
  "local_processing_agent_id": "local_processing_agent_id",
  "hybrid_deployment_agent_id": "hybrid_deployment_agent_id",
  "connect_card_config": {
    "redirect_uri": "https://your.site/path",
    "hide_setup_guide": true
  },
  "proxy_agent_id": "proxy_agent_id",
  "private_link_id": "private_link_id",
  "networking_method": "Directly",
  "config": {
    "has_manage_permissions": true,
    "host_ip": "string",
    "auth_type": "ConnectionString | AzureActiveDirectory",
    "sync_type": "Unpacked | Packed",
    "topics": [
      "string"
    ],
    "message_type": "Avro | Json | Text | Protobuf | Xml",
    "connection_string": "Connection String",
    "connection_method": "DIRECT | PRIVATE_LINK | SSH_TUNNEL",
    "namespace": "my_namespace",
    "schema_registry_secret": "schema_registry_secret",
    "subscriber_name": "subscriber_name",
    "host_user": "string",
    "asb_ip": "string",
    "schema_registry_key": "schema_registry_key",
    "schema_registry_urls": [
      "string"
    ],
    "schema": "schema_name"
  },
  "auth": {
    "refresh_token": "refresh_token",
    "client_access": {
      "client_secret": "my_client_secret",
      "client_id": "my_client_id"
    }
  }
}

Responses

201

Successful response

400

Bad request

Successful response schema

code

stringrequired

Response status code

example:

Success

message

string

Response status text

example:

Operation performed.

data

objectrequired

stringrequired

The unique identifier for the connection within the Fivetran system

example:

connection_id

service

stringrequired

azure_service_bus

The connector name within the Fivetran system

example:

google_ads

schema

stringrequired

The name used both as the connection's name within the Fivetran system and as the source schema's name within your destination

example:

schema.table

paused

booleanrequired

Specifies whether the connection is paused

status

objectrequired

tasks

array

The collection of tasks for the connection

code

string

Code

example:

resync_table_warning

message

string

Warning message

example:

Resync Table Warning

details

string

warnings

array

The collection of warnings for the connection

code

string

Code

example:

resync_table_warning

message

string

Warning message

example:

Resync Table Warning

details

string

schema_status

string

Schema status. Returned only for connectors that support Universal Column Masking flow.

example:

ready

update_state

stringrequired

The current data update state of the connection. The available values are:
- on_schedule - the sync is running smoothly, no delays
- delayed - the data is delayed for a longer time than expected for the update.

example:

delayed

setup_state

stringrequired

The current setup state of the connection. The available values are:
- incomplete - the setup config is incomplete, the setup tests never succeeded
- connected - the connection is properly set up
- broken - the connection setup config is broken.

example:

connected

sync_state

stringrequired

The current sync state of the connection. The available values are:
- scheduled - the sync is waiting to be run
- syncing - the sync is currently running
- paused - the sync is currently paused
- rescheduled - the sync is waiting until more API calls are available in the source service.

example:

scheduled

is_historical_sync

booleanrequired

The boolean specifying whether the connection should be triggered to re-sync all historical data. If you set this parameter to TRUE, the next scheduled sync will be historical. If the value is FALSE or not specified, the connection will not re-sync historical data. NOTE: When the value is TRUE, only the next scheduled sync will be historical, all subsequent ones will be incremental. This parameter is set to FALSE once the historical sync is completed.

rescheduled_for

string

The scheduled time for the next sync when sync_state is rescheduled. If schedule_type is manual, then the connection expects triggering the event at the designated time through the Sync Connection Data endpoint.

format:

date-time

example:

2024-12-01T15:43:29.013729Z

daily_sync_time

string

The connection daily sync start time that we return only when the sync frequency is set to 1440 (which means 24 hours) and the daily_sync_time parameter was set using the Create a Connection or Update a Connection request

example:

14:00

succeeded_at

string

The timestamp of the time the connection sync succeeded last time

format:

date-time

example:

2024-03-17T12:31:40.870504Z

sync_frequency

integerrequired

The connection sync frequency in minutes

format:

int32

enum:

"1""5""15""30""60""120""180""360""480""720""1440"

group_id

stringrequired

The unique identifier for the group within the Fivetran system

example:

group_id

connected_by

stringrequired

The unique identifier of the user who has created the connection in your account

example:

user_id

setup_tests

array

Setup tests results for this connection

title

stringrequired

Setup test title

example:

Test Title

status

stringrequired

Setup test status

enum:

"PASSED""SKIPPED""WARNING""FAILED""JOB_FAILED"

message

string

Setup test message

example:

Test Message

details

object

Setup test details

example:

...

source_sync_details

object

The additional information about the connection's state. The format of this parameter is specific for each connection type

service_version

integerrequired

The connector version within the Fivetran system

format:

int32

created_at

stringrequired

The timestamp of the time the connection was created in your account

format:

date-time

example:

2023-12-01T15:43:29.013729Z

failed_at

string

The timestamp of the time the connection sync failed last time

format:

date-time

example:

2024-04-01T18:13:25.043659Z

private_link_id

string

The unique identifier for the self-served private link that is used by the connection

example:

private_link_id

proxy_agent_id

string

The unique identifier for the proxy agent within the Fivetran system

example:

proxy_agent_id

networking_method

string

enum:

"Directly""SshTunnel""PrivateLink""ProxyAgent""UnmanagedPrivateLink""UnmanagedProxyAgent""Unknown"

connect_card

object

token

string

The connect-card auth token

example:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkIjp7ImxvZ2luIjp0cnVlLCJ1c2VyIjoiX2FjY291bnR3b3J0aHkiLCJhY2NvdW50IjoiX21vb25iZWFtX2FjYyIsImdyb3VwIjoiX21vb25iZWFtIiwiY29ubmVjdG9yIjoiY29iYWx0X2VsZXZhdGlvbiIsIm1ldGhvZCI6IlBiZkNhcmQiLCJpZGVudGl0eSI6ZmFsc2V9LCJpYXQiOjE2Njc4MzA2MzZ9.YUMGUbzxW96xsKJLo4bTorqzx8Q19GTrUi3WFRFM8BU

uri

string

The Connect Card URI for the user interface

example:

https://fivetran.com/connect-card/setup?auth=eyJ0eXAiOiJKV1QiLCJh...

pause_after_trial

booleanrequired

Specifies whether the connection should be paused after the free trial period has ended

data_delay_threshold

integer

Custom sync delay notification threshold in minutes. The default value is 0. This parameter is only used when data_delay_sensitivity set to CUSTOM.

format:

int32

data_delay_sensitivity

stringrequired

The level of data delay notification threshold. Possible values: LOW, NORMAL, HIGH, CUSTOM. The default value NORMAL. CUSTOM is only available for customers using the Enterprise plan or above.

enum:

"LOW""NORMAL""HIGH""CUSTOM"

schedule_type

stringrequired

The connection schedule configuration type. Supported values: auto, manual

example:

auto

local_processing_agent_id

string

(Deprecated) The unique identifier for the hybrid deployment agent within the Fivetran system

example:

local_processing_agent_id

connect_card_config

object

redirect_uri

stringrequired

The URI on your site we redirect the end user to after successful setup. The URI must start with the https or http prefix.

example:

https://your.site/path

hide_setup_guide

boolean

An optional parameter that lets you hide the embedded setup guide in the Connect Card.

example:

true

hybrid_deployment_agent_id

string

The unique identifier for the hybrid deployment agent within the Fivetran system. If not specified, the agent ID from the destination will be used

example:

hybrid_deployment_agent_id

config

object

has_manage_permissions

boolean

The boolean value specifying whether the connection string has manage permissions

title:

has_manage_permissions

example:

true

host_ip

string

The IP address of the host machine which we use to connect to ASB via ssh

title:

host_ip

example:

string

auth_type

object

The authentication mode to access the topic

title:

auth_type

enum:

"ConnectionString""AzureActiveDirectory"

sync_type

object

The sync type, which is based on the message type. For text and xml, packed is supported. For protobuf and avro, unpacked is supported. For json, both packed and unpacked are supported

title:

sync_type

enum:

"Packed""Unpacked"

topics

array

The comma-separated list of topics which should be synced. Required if you do not have manage permissions

example:

string

type:

string

message_type

object

The format of messages in the topic

title:

message_type

enum:

"Xml""Text""Json""Avro"

connection_string

string

The connection string used for authentication. Required if the authentication type is ConnectionString

title:

connection_string

format:

password

example:

Connection String

connection_method

object

The connection method

title:

connection_method

enum:

"SSH_TUNNEL""DIRECT""PRIVATE_LINK"

namespace

string

The ASB namespace which we have to sync. Required for AzureActiveDirectory authentication.

title:

namespace

example:

my_namespace

schema_registry_secret

string

The secret used to access the schema registry. Required for the avro and protobuf message types

title:

schema_registry_secret

format:

password

example:

schema_registry_secret

subscriber_name

string

The subscriber name. If the connection string does not have manage permission, you need to specify a subscriber name we can use to fetch data. If not specified, we default to fivetran_sub_<schema>

title:

subscriber_name

example:

subscriber_name

host_user

string

The username on the host machine which we use to connect to ASB via ssh

title:

host_user

example:

string

asb_ip

string

The IP address (or) the URL of ASB namespace

title:

asb_ip

example:

string

schema_registry_key

string

The key used to access the schema registry. Required for the avro and protobuf message types

title:

schema_registry_key

example:

schema_registry_key

schema_registry_urls

array

The comma-separated list of schema registry servers in the server:port format

example:

string

type:

string

public_key

string

Public key generated by Fivetran to be copied into the host-machine's authorized keys file.

example:

string

{
  "code": "Success",
  "message": "Operation performed.",
  "data": {
    "id": "connection_id",
    "service": "azure_service_bus",
    "schema": "schema.table",
    "paused": false,
    "status": {
      "tasks": [
        {
          "code": "resync_table_warning",
          "message": "Resync Table Warning",
          "details": "string"
        }
      ],
      "warnings": [
        {
          "code": "resync_table_warning",
          "message": "Resync Table Warning",
          "details": "string"
        }
      ],
      "schema_status": "ready",
      "update_state": "delayed",
      "setup_state": "connected",
      "sync_state": "scheduled",
      "is_historical_sync": false,
      "rescheduled_for": "2024-12-01T15:43:29.013729Z"
    },
    "daily_sync_time": "14:00",
    "succeeded_at": "2024-03-17T12:31:40.870504Z",
    "sync_frequency": 1440,
    "group_id": "group_id",
    "connected_by": "user_id",
    "setup_tests": [
      {
        "title": "Test Title",
        "status": "FAILED",
        "message": "Test Message",
        "details": "..."
      }
    ],
    "source_sync_details": {},
    "service_version": 0,
    "created_at": "2023-12-01T15:43:29.013729Z",
    "failed_at": "2024-04-01T18:13:25.043659Z",
    "private_link_id": "private_link_id",
    "proxy_agent_id": "proxy_agent_id",
    "networking_method": "Directly",
    "connect_card": {
      "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkIjp7ImxvZ2luIjp0cnVlLCJ1c2VyIjoiX2FjY291bnR3b3J0aHkiLCJhY2NvdW50IjoiX21vb25iZWFtX2FjYyIsImdyb3VwIjoiX21vb25iZWFtIiwiY29ubmVjdG9yIjoiY29iYWx0X2VsZXZhdGlvbiIsIm1ldGhvZCI6IlBiZkNhcmQiLCJpZGVudGl0eSI6ZmFsc2V9LCJpYXQiOjE2Njc4MzA2MzZ9.YUMGUbzxW96xsKJLo4bTorqzx8Q19GTrUi3WFRFM8BU",
      "uri": "https://fivetran.com/connect-card/setup?auth=eyJ0eXAiOiJKV1QiLCJh..."
    },
    "pause_after_trial": false,
    "data_delay_threshold": 0,
    "data_delay_sensitivity": "NORMAL",
    "schedule_type": "auto",
    "local_processing_agent_id": "local_processing_agent_id",
    "connect_card_config": {
      "redirect_uri": "https://your.site/path",
      "hide_setup_guide": true
    },
    "hybrid_deployment_agent_id": "hybrid_deployment_agent_id",
    "config": {
      "has_manage_permissions": true,
      "host_ip": "string",
      "auth_type": "ConnectionString | AzureActiveDirectory",
      "sync_type": "Unpacked | Packed",
      "topics": [
        "string"
      ],
      "message_type": "Avro | Json | Text | Protobuf | Xml",
      "connection_string": "Connection String",
      "connection_method": "DIRECT | PRIVATE_LINK | SSH_TUNNEL",
      "namespace": "my_namespace",
      "schema_registry_secret": "schema_registry_secret",
      "subscriber_name": "subscriber_name",
      "host_user": "string",
      "asb_ip": "string",
      "schema_registry_key": "schema_registry_key",
      "schema_registry_urls": [
        "string"
      ],
      "public_key": "string"
    }
  }
}