Connector Management
REST API supports the following connector management actions:
- Create a connector
- Retrieve connector details
- Modify a connector
- Sync connector data
- Re-sync connector table data
- Run connector setup tests
- Delete a connector
- Retrieve a connector schema config
- Retrieve source table columns config
- Reload a connector schema config
- Modify a connector schema config
- Modify a connector database schema config
- Modify a connector table config
- Modify a connector column config
- Use Case: Create a new connector based on an existing connector's parameters
Create a Connector
Creates a new connector within a specified group in your Fivetran account. Runs setup tests and returns testing results.
Request
POST api.fivetran.com/v1/connectors
{
"service": "criteo",
"group_id": "projected_sickle",
"trust_certificates": true,
"run_setup_tests": true,
"paused": true,
"config": {
"schema": "criteo",
"username": "myuser",
"password": "mypassword",
"app_token": "myapptoken"
}
}
Payload parameters
| Name | Description |
|---|---|
group_id (required) |
The unique identifier for the group within the Fivetran system. Find you group_id by fetching your account's group list. |
service (required) |
The name for the connector type within the Fivetran system. |
config (required) |
The connector setup configuration. The format is specific for each connector. |
paused |
The boolean specifying whether connector should be paused. |
trust_certificates |
Specifies whether we should trust the certificate automatically. Applicable only for database connectors. The default value is false. If a certificate is not trusted automatically it has to be approved with Certificates Management API. |
run_setup_tests |
Specifies whether setup tests should be run automatically. The default value is true. |
Response
HTTP 201 Created
{
"code": "Success",
"message": "Connector has been created",
"data": {
"id": "speak_inexpensive",
"group_id": "projected_sickle",
"service": "criteo",
"service_version": 0,
"schema": "criteo",
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency":60,
"status": {
"setup_state": "incomplete",
"sync_state": "scheduled",
"update_state": "on_schedule",
"is_historical_sync": true,
"tasks": [],
"warnings": []
},
"setup_tests": [{
"title": "Validate Login",
"status": "FAILED",
"message": "Invalid login credentials"
}],
"config": {
"username": "myuser",
"password": "******",
"api_token": "******",
"service_version": "0"
}
}
}
If run_setup_tests is set to false in the request the response will not contain setup_tests field.
See how to create a new connector based on an existing connector's parameters.
Retrieve Connector Details
Returns a connector object if a valid identifier was provided.
Request
GET api.fivetran.com/v1/connectors/{connector_id}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"id": "speak_inexpensive",
"group_id": "projected_sickle",
"service": "criteo",
"service_version": 0,
"schema": "criteo",
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency": 60,
"status": {
"setup_state": "incomplete",
"sync_state": "scheduled",
"update_state": "delayed",
"is_historical_sync": true,
"tasks": [],
"warnings": []
},
"config": {
"username": "myuser",
"password": "******",
"api_token": "******",
"service_version": "0"
}
}
}
Fields
| Name | Description |
|---|---|
id |
The unique identifier for the connector within the Fivetran system. |
group_id |
The unique identifier for the group within the Fivetran system. |
service |
The name for the connector type within the Fivetran system. |
service_version |
The version of the connector type within the Fivetran system. |
schema |
The name that you'd like to give the connector within the Fivetran system and the source schema name within your destination. |
connected_by |
The unique identifier for the user, setting up the connector in your account. |
created_at |
The timestamp of when the connector was created in your account. |
succeeded_at |
The timestamp of when the connector sync succeeded last time |
failed_at |
The timestamp of when the connector sync failed last time |
sync_frequency |
The connector sync frequency in minutes |
status.setup_state |
The current setup state of the connector, supported values: 'incomplete' - setup config is incomplete, setup tests never succeeded 'connected' - connector is properly set up 'broken' - connector setup config is broken |
status.sync_state |
The current sync state of the connector, supported values: 'scheduled' - sync is waiting to be run 'syncing' - sync is currently running 'paused' - sync is currently paused 'rescheduled' - sync is waiting until more API calls available in the source service |
update_state |
The current data update state of the connector, supported values: 'on_schedule' - sync running smoothly, no delays 'delayed' - data is delayed longer than set update expectations |
is_historical_sync |
The boolean value specifying whether connector is at the historical data sync stage (also true for resyncing connectors) |
tasks |
The collection of tasks for the connector |
warnings |
The collection of warnings for the connector |
config |
The connector setup configuration. The format is specific for each connector. |
Modify a Connector
Updates information for an existing connector within your Fivetran account.
Request
PATCH api.fivetran.com/v1/connectors/{connector_id}
{
"paused": false,
"sync_frequency": 60,
"trust_certificates": true,
"run_setup_tests": true,
"config": {
"username": "newuser",
"password": "newpassword"
},
"schedule_type": "manual"
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Payload parameters
| Name | Description |
|---|---|
paused |
The boolean specifying whether connector should be paused |
sync_frequency |
The connector sync frequency in minutes. This can include: 5, 15, 30, 60, 120, 180, 360, 480, 720, 1440. |
config |
The connector setup configuration. The format is specific for each connector. |
trust_certificates |
Specifies whether we should trust the certificate automatically. Applicable only for database connectors, and when config parameter is specified. The default value is false. If a certificate is not trusted automatically it has to be approved using the Certificates Management API. |
is_historical_sync |
The boolean specifying whether connector should be triggered to re-sync all historical data. |
schedule_type |
The connector schedule config type. Supported values: 'auto', 'manual'. Allows you to disable or enable automatic data sync on a schedule. If you specify this parameter as 'manual' automatic data sync will be disabled but you'll be able to trigger data sync via the Sync Connector Data endpoint. |
run_setup_tests |
Specifies whether setup tests should be run automatically. The default value is true. |
None of the paused, sync_frequency, config, is_historical_sync, schedule_type parameters is required, but at least one of them has to be specified for modify request to succeed.
Response
HTTP 200 OK
{
"code": "Success",
"message": "Connector has been updated",
"data": {
"id": "speak_inexpensive",
"group_id": "projected_sickle",
"service": "criteo",
"service_version": 0,
"schema": "criteo",
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency":60,
"status": {
"setup_state": "incomplete",
"sync_state": "scheduled",
"update_state": "on_schedule",
"is_historical_sync": true,
"tasks": [],
"warnings": []
},
"setup_tests": [{
"title": "Validate Login",
"status": "FAILED",
"message": "Invalid login credentials"
}],
"config": {
"username": "newuser",
"password": "******",
"api_token": "******",
"service_version": "0"
}
}
}
If run_setup_tests is set to false in the request the response will not contain setup_tests field.
Sync Connector Data
Triggers data sync for an existing connector within your Fivetran account without waiting for the next scheduled sync. This action does not override the standard sync frequency you defined in the Fivetran dashboard.
If a data sync is already in progress, that sync is immediately stopped and restarted. If the connector is paused, the data sync will be scheduled when the connector is re-enabled.
Request
POST api.fivetran.com/v1/connectors/{connector_id}/force
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Payload
The request body must be empty.
Response
HTTP 200 OK
{
"code": "Success",
"message": "Sync has been successfully triggered for connector with id 'connector_id1'"
}
Re-sync Connector Table Data
Triggers a historical sync of all data for a single table within a connector. This action does not override the standard sync frequency you defined in the Fivetran dashboard.
If the connector is paused, the table sync will be scheduled when the connector is re-enabled. If a data sync is already in progress we will try to complete it, and if it is unsuccessful the request will be declined and the HTTP 409 Conflict error will be returned.
Request
POST api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}/tables/{table}/resync
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
schema (required) |
The database schema name within your destination (different from the connector schema). |
table (required) |
The table name within your database schema. |
To make the request successful you need to specify the correct parameters. You can access the exact name of your database schema and table in the Schema tab of your connector. See example below:
Payload
The request body must be empty.
Response
HTTP 200 OK
{
"code": "Success",
"message": "Re-sync has been successfully triggered for 'schema1.table1'"
}
Run connector setup tests
Runs setup tests for an existing connector within your Fivetran account.
Request
POST api.fivetran.com/v1/connectors/{connector_id}/test
{
"trust_certificates": true
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Payload parameters
| Name | Description |
|---|---|
trust_certificates |
Specifies whether we should trust the certificate automatically. Applicable only for database connectors. The default value is false. If a certificate is not trusted automatically it has to be approved using the Certificates Management API. |
Response
HTTP 200 OK
{
"code": "Success",
"message": "Setup tests were completed",
"data": {
"id": "speak_inexpensive",
"group_id": "projected_sickle",
"service": "criteo",
"service_version": 0,
"schema": "criteo",
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency":60,
"status": {
"setup_state": "incomplete",
"sync_state": "scheduled",
"update_state": "on_schedule",
"is_historical_sync": true,
"tasks": [],
"warnings": []
},
"setup_tests": [{
"title": "Validate Login",
"status": "FAILED",
"message": "Invalid login credentials"
}],
"config": {
"username": "newuser",
"password": "******",
"api_token": "******",
"service_version": "0"
}
}
}
Delete a Connector
Deletes a connector from your Fivetran account.
Request
DELETE api.fivetran.com/v1/connectors/{connector_id}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Response
HTTP 200 OK
{
"code": "Success",
"message": "Connector with id 'speak_inexpensive' has been deleted"
}
Retrieve a Connector Schema Config
Returns a connector schema config for an existing connector within your Fivetran account.
Request
GET api.fivetran.com/v1/connectors/{connector_id}/schemas
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": false,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"enabled": true,
"hashed": true
}
}
},
"table_2": {
"enabled": true
}
}
},
"schema_2": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"columns": {
"column_1": {
"enabled": false
}
}
},
"table_2": {
"enabled": false
}
}
}
}
}
}
Fields
| Name | Description |
|---|---|
enable_new_by_default |
The boolean value specifying whether to enable new schemas and tables by default. |
schema.enabled |
The boolean value specifying whether a schema will be synced into the destination. |
table.enabled |
The boolean value specifying whether a table will be synced into the destination. |
column.enabled |
The boolean value specifying whether a column will be synced into the destination. |
column.hashed |
The boolean value specifying whether a column is hashed or not. |
The response contains only the difference between your selections and the schema config. Schema config includes schemas, tables, and columns. If you have not specified any schema configurations that differ from the default, the response will consist of only the top schema level.
Retrieve Source Table Columns Config
Returns source table columns config for an existing connector within your Fivetran account.
Request
GET api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}/tables/{table}/columns
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
schema (required) |
The database schema name within your source (different from the connector schema which corresponds to schema name in your destination). |
table (required) |
The table name within your source schema. |
Response
HTTP 200 OK
{
"code": "Success",
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"enabled": false,
"hashed": false
}
}
}
The response contains an array of columns with Fivetran sync settings for each column.
Fields
| Name | Description |
|---|---|
| enabled | The boolean value specifying whether a column should be synced into the destination. |
| hashed | The boolean value specifying whether a column should be hashed. |
Since we interact with the source fetching data may take long time. Response time depends on the connection to the source.
Reload a Connector Schema Config
Reloads a connector schema config for an existing connector within your Fivetran account.
We advise that you use this method if the connector was recently created or its schema is outdated.
Request
POST api.fivetran.com/v1/connectors/{connector_id}/schemas/reload
{
"exclude_mode":"PRESERVE"
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Payload
| Name | Description | Possible Values |
|---|---|---|
exclude_mode |
Specifies whether all schemas and tables will be enabled or disabled in standard config. | EXCLUDE, INCLUDE and PRESERVE. The default value is PRESERVE. |
The request body can be empty because it contains only the one optional parameter exclude_mode with the PRESERVE value by default.
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": false,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"enabled": true,
"hashed": true
}
}
},
"table_2": {
"enabled": true
}
}
},
"schema_2": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"columns": {
"column_1": {
"enabled": false
}
}
},
"table_2": {
"enabled": false
}
}
}
}
}
}
Fields
| Name | Description |
|---|---|
enable_new_by_default |
The boolean value specifying whether to enable new schemas and tables by default. |
schemas |
The set of schemas within your connector schema config will be synced into the destination. |
schema.enabled |
The boolean value specifying whether a schema will be synced into the destination. |
tables |
The set of tables within your database schema config will be synced into the destination. |
table.enabled |
The boolean value specifying whether a table will be synced into the destination. |
columns |
The set of columns within your table schema config will be synced into the destination. |
column.enabled |
The boolean value specifying whether a column will be synced into the destination. |
column.hashed |
The boolean value specifying whether a column is hashed or not. |
This method reloads a full schema from the connector's data source, and it may take a long time to complete the request. The method execution speed depends on the schema size, and the number of databases, tables and columns. To retrieve the connector schema config without reload use the Retrieve a Connector Schema Config endpoint.
By specifying the exclude_mode parameter, you can completely enable or disable all schemas, tables and columns when reloading a connector schema config.
The default PRESERVE parameter value means that all your selections in the standard config preserve their state.
The response contains only the difference between your selections and the schema config. Schema config includes schemas, tables, and columns. If you have not specified any schema configurations that differ from the default, the response will consist of only the top schema level.
Modify a Connector Schema Config
Updates the schema config for an existing connector within your Fivetran account (for a single schema for a connector with multiple schemas).
Request
PATCH api.fivetran.com/v1/connectors/{connector_id}/schemas
{
"enable_new_by_default": true,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"hashed": true
}
}
}
}
},
"schema_2": {
"enabled": false
}
}
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
Payload parameters
| Name | Description |
|---|---|
enable_new_by_default |
The boolean value specifying whether to enable new schemas, tables, and columns by default. |
schema.enabled |
The boolean value specifying whether a schema should be synced into the destination. |
table.enabled |
The boolean value specifying whether a table should be synced into the destination. |
column.enabled |
The boolean value specifying whether a column should be synced into the destination. |
column.hashed |
The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": true
}
}
}
}
},
"schema_2": {
"enabled": false,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. Schema config includes schemas, tables, and columns. If you have not specified any schema configurations that differ from the default, the response will consist of only the top schema level.
Modify a Connector Database Schema Config
Updates the database schema config for an existing connector within your Fivetran account (for a single schema within a connector with multiple schemas).
Request
PATCH api.fivetran.com/v1/connectors/{connector_id}/schemas/{schemaName}
{
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"hashed": true
}
}
}
}
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
schema (required) |
The database schema name within your destination (different from the connector schema). |
Payload parameters
| Name | Description |
|---|---|
enabled |
The boolean value specifying whether a schema should be synced into the destination. |
table.enabled |
The boolean value specifying whether a table should be synced into the destination. |
column.enabled |
The boolean value specifying whether a column should be synced into the destination. |
column.hashed |
The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": true
}
}
}
}
},
"schema_2": {
"enabled": false,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. Schema config includes schemas, tables, and columns. If you have not specified any schema configurations that differ from the default, the response will consist of only the top schema level.
Modify a Connector Table Config
Updates the table config within your database schema for an existing connector within your Fivetran account.
Request
PATCH api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}/tables/{table}
{
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"hashed": true
}
}
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
schema (required) |
The database schema name within your destination (different from the connector schema). |
table (required) |
The table name within your database schema. |
Payload parameters
| Name | Description |
|---|---|
enabled |
The boolean value specifying whether a table should be synced into the destination. |
column.enabled |
The boolean value specifying whether a column should be synced into the destination. |
column.hashed |
The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": true
}
}
}
}
},
"schema_2": {
"enabled": false,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. Schema config includes schemas, tables, and columns. If you have not specified any schema configurations that differ from the default, the response will consist of only the top schema level.
Modify a Connector Column Config
Updates the column config within your table for an existing connector within your Fivetran account.
Request
PATCH api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}/tables/{table}/columns/{column}
{
"enabled": true,
"hashed": false
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) |
The unique identifier for the connector within the Fivetran system. |
schema (required) |
The database schema name within your destination (different from the connector schema). |
table (required) |
The table name within your database schema. |
column (required) |
The column name within your table. |
Payload parameters
| Name | Description |
|---|---|
enabled |
The boolean value specifying whether a column should be synced into the destination. |
hashed |
The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false,
"columns": {
"column_1": {
"enabled": true,
"hashed": false
},
"column_2": {
"enabled": true,
"hashed": true
}
}
}
}
},
"schema_2": {
"enabled": false,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": false
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. Schema config includes schemas, tables, and columns. If you have not specified any schema configurations that differ from the default, the response will consist of only the top schema level.
Use Case: Create a new connector based on an existing connector's parameters
You can create new connectors using the parameters of an existing connector.
-
Retrieve the connector object details. See Retrieve Connector Details.
Request
GET api.fivetran.com/v1/connectors/{connector_id}Path parameters
Name Description connector_id(required)The unique identifier for the connector within the Fivetran system. Response
HTTP 200 OK -
Make a note of the following fields from the API response:
{ "group_id": "projected_sickle" "service": "criteo" "config": { "username": "myuser", "password": "******", "api_token": "******", "service_version": "0" } } -
Create the new connector using the fields from the previous step. See Create a connector.
Request
POST api.fivetran.com/v1/connectors{ "service": "criteo", "group_id": "projected_sickle", "trust_certificates": true, "run_setup_tests": true, "config": { "schema": "criteo", "username": "myuser", "password": "mypassword", "app_token": "myapptoken" } }Payload parameters
Name Description group_id(required)The unique identifier for the group within the Fivetran system. Find you group_idby fetching your account's group list.service(required)The name for the connector type within the Fivetran system. config(required)The connector setup configuration. The format is specific for each connector. trust_certificatesSpecifies whether we should trust the certificate automatically. Applicable only for database connectors. The default value is false. If a certificate is not trusted automatically it has to be approved with Certificates Management API.run_setup_testsSpecifies whether setup tests should be run automatically. The default value is true.Response
HTTP 201 Created