Connector Management
REST API supports the following connector management actions:
- Retrieve connector types
- Retrieve connector type details
- Create a connector
- List all connectors within account
- Retrieve connector details
- Modify a connector
- Sync connector data
- Re-sync connector data (historical sync)
- 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
- Create 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
- Retrieve Connector State
- Update Connector State
- Delete Blocked Column
- Delete Blocked Columns
Retrieving the exact names of schemas, tables, and columns
In order for the request to succeed, you must specify the correct parameter values. When you call endpoints that require passing schema, table, or column names as path or payload parameters, specify the names exactly as they appear in the source.
IMPORTANT: Do not rely on the example requests and responses in our REST API documentation or on how the names appear in your destination. Fivetran transforms schema, table, and column names according to our naming conventions.
We recommend that you retrieve the exact schema, table, and column names of your connector before you call endpoints that require passing schema, table, or column as path or payload parameters.
You can use either of the following methods:
In your Fivetran dashboard: Go to the Schema tab of your connector and use the schema, table, or column names displayed there. See the following example:
Using Fivetran REST API: Call the Retrieve a Connector Schema Config endpoint.
NOTE: The connector schemas define what tables and columns present in the source your connector syncs. Most Fivetran REST API endpoint requests and responses use the connector schema names as path or payload parameters. On the other hand, the destination schema that we use as a name of your connector defines how the data is stored in your destination. You specify the destination schema name either in the connector setup form or as a value of the
schemapayload parameter in the Create a Connector endpoint request when creating a connector.
Retrieve connector types
Returns all available source types within your Fivetran account. This endpoint makes it easier to display Fivetran connectors within your application because it provides metadata including the proper source name (‘Facebook Ads’ instead of facebook_ads), the source icon, and links to Fivetran resources. As we update source names and icons, that metadata will automatically update within this endpoint.
NOTE: In addition, you can use the following unauthenticated request that returns the list of all supported connectors:
GET https://api.fivetran.com/connector-types
Request
GET https://api.fivetran.com/v1/metadata/connector-types
Query parameters
| Name | Description |
|---|---|
cursor | The paging cursor. Read more about pagination in our documentation |
limit | The number of records to fetch per page, accepts a number in the range 1..1000. The default value is 100 |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"items": [
{
"id": "facebook_ads",
"name": "Facebook Ads",
"type": "Marketing",
"connector_class": "standard",
"description": "Facebook Ads provides attribute data on Facebook Ads",
"icon_url": "https://fivetran.com/integrations/facebook/resources/facebook.svg",
"icons": [
"https://fivetran.com/integrations/facebook/resources/facebook-logo.svg",
"https://fivetran.com/integrations/facebook/resources/facebook-logo.png"
],
"link_to_docs": "https://fivetran.com/docs/connectors/applications/facebook-ads",
"link_to_erd": "https://fivetran.com/docs/connectors/applications/facebook-ads#schemainformation",
"service_status": "general_availability",
"service_status_updated_at": "2024-01-01",
"supported_features": [
{
"id": "CUSTOM_DATA",
"notes": ""
},
{
"id": "CAPTURE_DELETES",
"notes": ""
},
{
"id": "DATA_BLOCKING",
"notes": "Column level"
},
{
"id": "COLUMN_HASHING",
"notes": ""
},
{
"id": "RE_SYNC",
"notes": ""
},
{
"id": "HISTORY",
"notes": ""
},
{
"id": "API_CONFIGURABLE",
"notes": "API Configuration"
},
{
"id": "PRIORITY_FIRST_SYNC",
"notes": "All tables"
},
{
"id": "FIVETRAN_DATA_MODELS",
"notes": ""
},
{
"id": "PRIVATE_NETWORKING",
"notes": ""
},
{
"id": "AUTHORIZATION_VIA_API",
"notes": ""
}
]
}
],
"next_cursor": "eyJza2lwIjoxMDB9"
}
}
| Name | Description |
|---|---|
items | The collection of connector types describing their metadata. |
id | The connector type identifier within the Fivetran system. |
name | The connector service name within the Fivetran system. |
type | The connector service type |
connector_class | The connector class. The supported values are: standard, lite. Learn more in our Differences between Standard and Lite connectors documentation. |
description | The description characterizing the purpose of the connector. |
icon_url | The icon resource URL |
icons | Beta The set of additional icon resource URLs in different formats (.svg, .png). Updating this list is not a breaking change. The set of icon URLs or the icons themselves may be changed. |
link_to_docs | The link to the connector documentation. |
link_to_erd | The link to the connector ERD (entity–relationship diagram). |
service_status | The current availability status of the connector. The supported values are: general_availability, beta, private_preview, sunset, development |
service_status_updated_at | The date (yyyy-MM-dd) the connector status was updated to the current availability status of the connector. |
supported_features.id | The unique identifier of a feature supported by the connector. The supported values are: CUSTOM_DATA, CAPTURE_DELETES, DATA_BLOCKING, COLUMN_HASHING, RE_SYNC, HISTORY, API_CONFIGURABLE, PRIORITY_FIRST_SYNC, RE_SYNC, FIVETRAN_DATA_MODELS, PRIVATE_NETWORKING, AUTHORIZATION_VIA_API |
supported_features.notes | Additional information about the feature support of a specific connector. |
next_cursor | The value of the cursor parameter for the next page. |
Retrieve connector type details
Returns configuration parameters and authorization parameters for a specified connector type.
Request
GET api.fivetran.com/v1/metadata/connector-types/{connector_type}
Query parameters
| Name | Description |
|---|---|
connector_type | The connector type identifier within the Fivetran system. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"id": "connector_type",
"name": "Service Display Name",
"type": "Marketing",
"connector_class": "standard",
"description": "Service detailed description",
"icon_url": "https://fivetran.com/integrations/link/to/icon.svg",
"icons": [
"https://fivetran.com/integrations/link/to/service-logo.svg",
"https://fivetran.com/integrations/link/to/service-logo.png"
],
"link_to_docs": "https://fivetran.com/docs/service-docs",
"link_to_erd": "https://fivetran.com/docs/link/to/service#schemainformation",
"service_status": "general_availability",
"service_status_updated_at": "2024-01-01",
"supported_features": [
{
"id": "CUSTOM_DATA",
"notes": ""
},
{
"id": "CAPTURE_DELETES",
"notes": ""
},
{
"id": "DATA_BLOCKING",
"notes": "Column level"
},
{
"id": "COLUMN_HASHING",
"notes": ""
},
{
"id": "RE_SYNC",
"notes": ""
},
{
"id": "HISTORY",
"notes": ""
},
{
"id": "API_CONFIGURABLE",
"notes": "API Configuration"
},
{
"id": "PRIORITY_FIRST_SYNC",
"notes": "All tables"
},
{
"id": "FIVETRAN_DATA_MODELS",
"notes": ""
},
{
"id": "PRIVATE_NETWORKING",
"notes": ""
},
{
"id": "AUTHORIZATION_VIA_API",
"notes": ""
}
],
"auth": {
"type": "object",
"properties": {
"access_token": {
"type": "string",
"description": "The long-lived Access token carries the information necessary to access API resources."
},
...
}
}
"config": {
"type": "object",
"properties": {
"schema": {
"type": "string",
"description": "Destination schema. Schema is permanent and cannot be changed after connection creation"
},
"sync_mode": {
"description": "",
"one_of": [
{
"type": "string",
"description": "Automatically sync all existing and new client accounts",
"const": "AllAccounts"
},
{
"type": "string",
"description": "Select client accounts for sync",
"const": "SpecificAccounts"
},
{
"type": "string",
"description": "Select manager accounts whose clients you want to sync",
"const": "ManagerAccounts"
}
]
},
...
},
"required": [
"schema",
...
]
}
}
}
| Name | Description |
|---|---|
id | The connector type identifier within the Fivetran system. |
name | The connector service name within the Fivetran system. |
type | The connector service type |
connector_class | The connector class. The supported values are: standard, lite. Learn more in our Differences between Standard and Lite connectors documentation. |
description | The description characterizing the purpose of the connector. |
icon_url | The icon resource URL |
icons | Beta The set of additional icon resource URLs in different formats (.svg, .png). Updating this list is not a breaking change. The set of icon URLs or the icons themselves may be changed. |
link_to_docs | The link to the connector documentation. |
link_to_erd | The link to the connector ERD (entity–relationship diagram). |
auth | Metadata for authorization fields (optional). |
service_status | The current availability status of the connector. The supported values are: general_availability, beta, private_preview, sunset, development |
service_status_updated_at | The date (yyyy-MM-dd) the connector status was updated to the current availability status. |
supported_features.id | The unique identifier of a feature supported by the connector. The supported values are: CUSTOM_DATA, CAPTURE_DELETES, DATA_BLOCKING, COLUMN_HASHING, RE_SYNC, HISTORY, API_CONFIGURABLE, PRIORITY_FIRST_SYNC, RE_SYNC, FIVETRAN_DATA_MODELS, PRIVATE_NETWORKING, AUTHORIZATION_VIA_API |
supported_features.notes | Additional information about the feature support of a specific connector. |
config | Metadata for configuration fields. |
Schema format is compatible with JSON-Schema Draft-06.
Create a Connector
Creates a new connector within a specified group in your Fivetran account. Runs setup tests and returns testing results.
Request
POST https://api.fivetran.com/v1/connectors
{
"service": "criteo",
"group_id": "projected_sickle",
"trust_certificates": true,
"trust_fingerprints": "true",
"run_setup_tests": true,
"paused": true,
"pause_after_trial": true,
"sync_frequency": 1440,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"daily_sync_time": "03:00",
"local_processing_agent_id": "lpa-id",
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "1",
"networking_method": "PrivateLink",
"config": {
"schema": "criteo",
"username": "myuser",
"password": "mypassword",
"app_token": "myapptoken"
},
"auth": {
"client_access": {
"client_id": "my_client_id",
"client_secret": "my_client_secret"
},
"refresh_token": "my_refresh_token"
},
"connect_card_config": {
"redirect_uri": "http://test_domain.com"
}
}
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. |
auth | The connector authorization settings. Can be used to authorize a connector using your external client credentials. The format is specific for each connector. |
paused | Specifies whether the connector is paused. |
pause_after_trial | Specifies whether the connector should be paused after the free trial period has ended. If this parameter is omitted in the request, then we use the default value false. |
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 set to be trusted automatically, it has to be approved using the Approve a Connector Certificate endpoint. |
trust_fingerprints | Specifies whether we should trust the SSH fingerprint automatically. Applicable only for database connectors. The default value is FALSE. If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a connector fingerprint. |
run_setup_tests | Specifies whether the setup tests should be run automatically. The default value is TRUE. |
sync_frequency | The connector sync frequency in minutes. The supported values are: 5, 15, 30, 60, 120, 180, 360, 480, 720, 1440. |
data_delay_sensitivity | Delay Threshold. Possible values: LOW, NORMAL, HIGH, CUSTOM. The default value is NORMAL. CUSTOM is only available for customers using the Enterprise plan or above. |
data_delay_threshold | Custom sync delay notification threshold in minutes. The default value is 0. This parameter is used when data_delay_sensitivity set to CUSTOM. |
daily_sync_time | 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. |
schedule_type | The optional parameter that defines the connector sync scheduling type. Supported values: AUTO, MANUAL. If set to MANUAL, the automatic data sync is disabled, and you need to trigger syncs manually using the Sync Connector Data endpoint. The default value is AUTO. |
connect_card_config | The optional parameter that defines parameters for the Connect Card field generation. If specified, run_setup_tests must not be set to TRUE |
connect_card_config.redirect_uri | The URI on your site where we will redirect the end user after successful setup. The URI must start with the https or http prefix. |
connect_card_config.hide_setup_guide | An optional parameter that lets you hide the embedded setup guide in the Connect Card window. |
local_processing_agent_id | The local processing agent ID that refers to the controller created for the group the connection belongs to. If the value is specified, the system will try to associate the connection with an existing agent. |
proxy_agent_id | The proxy agent ID. |
private_link_id | The private link ID. |
networking_method | Possible values: Directly, PrivateLink, SshTunnel, ProxyAgent |
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",
"paused": true,
"pause_after_trial": true,
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency": 1440,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"daily_sync_time": "03:00",
"local_processing_agent_id": "lpa-id",
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "1",
"networking_method": "PrivateLink",
"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"
},
"connect_card": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkIjp7ImxvZ2luIjp0cnVlLCJ1c2VyIjoiX2FjY291bnR3b3J0aHkiLCJhY2NvdW50IjoiX21vb25iZWFtX2FjYyIsImdyb3VwIjoiX21vb25iZWFtIiwiY29ubmVjdG9yIjoiY29iYWx0X2VsZXZhdGlvbiIsIm1ldGhvZCI6IlBiZkNhcmQiLCJpZGVudGl0eSI6ZmFsc2V9LCJpYXQiOjE2Njc4MzA2MzZ9.YUMGUbzxW96xsKJLo4bTorqzx8Q19GTrUi3WFRFM8BU",
"uri": "https://fivetran.com/connect-card/setup?redirect_uri=http://test_domain.com&auth=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkIjp7ImxvZ2luIjp0cnVlLCJ1c2VyIjoiX2FjY291bnR3b3J0aHkiLCJhY2NvdW50IjoiX21vb25iZWFtX2FjYyIsImdyb3VwIjoiX21vb25iZWFtIiwiY29ubmVjdG9yIjoiY29iYWx0X2VsZXZhdGlvbiIsIm1ldGhvZCI6IlBiZkNhcmQiLCJpZGVudGl0eSI6ZmFsc2V9LCJpYXQiOjE2Njc4MzA2MzZ9.YUMGUbzxW96xsKJLo4bTorqzx8Q19GTrUi3WFRFM8BU"
},
"connect_card_config": {
"redirect_uri": "http://test_domain.com"
}
}
}
If run_setup_tests is set to FALSE in the request, the response will not contain the setup_tests field.
See how to create a new connector based on an existing connector's parameters.
List All Connectors within Account
Returns a list of all accessible connectors within your Fivetran account.
Request
GET https://api.fivetran.com/v1/connectors
Query parameters
| Name | Description |
|---|---|
cursor | Paging cursor. Read more about pagination |
limit | Number of records to fetch per page. Accepts a number in the range from 1 to 1000, the default value is 100 |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"items": [
{
"id": "iodize_impressive",
"group_id": "projected_sickle",
"service": "salesforce",
"service_version": 1,
"schema": "salesforce",
"connected_by": "concerning_batch",
"created_at": "2018-07-21T22:55:21.724201Z",
"succeeded_at": "2018-12-26T17:58:18.245Z",
"failed_at": "2018-08-24T15:24:58.872491Z",
"sync_frequency": 60,
"status": {
"setup_state": "connected",
"sync_state": "paused",
"update_state": "delayed",
"is_historical_sync": false,
"tasks": [],
"warnings": []
}
}
],
"next_cursor": "eyJza2lwIjoxfQ"
}
}
Retrieve Connector Details
Returns a connector object if a valid identifier was provided.
Request
GET https://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": "connector_id",
"group_id": "group_id",
"service": "adwords",
"service_version": 4,
"schema": "adwords.schema",
"paused": true,
"pause_after_trial": true,
"connected_by": "monitoring_assuring",
"created_at": "2020-03-11T15:03:55.743708Z",
"succeeded_at": "2020-03-17T12:31:40.870504Z",
"failed_at": "2021-01-15T10:55:00.056497Z",
"sync_frequency": 360,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"schedule_type": "auto",
"local_processing_agent_id": "lpa-id",
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "1",
"networking_method": "PrivateLink",
"status": {
"setup_state": "broken",
"schema_status": "ready",
"sync_state": "scheduled",
"update_state": "delayed",
"is_historical_sync": false,
"tasks": [
{
"code": "reconnect",
"message": "Reconnect"
}
],
"warnings": []
},
"config": {
"sync_mode": "SpecificAccounts",
"customer_id": "XXX-XXX-XXXX",
"accounts": [
"1234567890"
],
"conversion_window_size": 30,
"report_type": "AD_PERFORMANCE_REPORT",
"fields": [
"PolicySummary",
"AdType",
"Date"
]
},
"source_sync_details": {
"accounts": [
"1234567890"
]
}
}
}
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 connector type name within the Fivetran system. |
service_version | The connector type version within the Fivetran system. |
schema | The name used both as the connector's name within the Fivetran system and as the source schema's name within your destination. |
paused | The boolean specifying whether the connector is paused. |
pause_after_trial | The boolean specifying whether the connector should be paused after the free trial period has ended. |
connected_by | The unique identifier of the user who has created the connector in your account. |
created_at | The timestamp of the time the connector was created in your account. |
succeeded_at | The timestamp of the time the connector sync succeeded last time. |
failed_at | The timestamp of the time the connector sync failed last time. |
sync_frequency | The connector sync frequency in minutes. |
data_delay_sensitivity | the delay threshold. |
data_delay_threshold | The custom sync delay notification threshold in minutes. |
daily_sync_time | The connector daily sync start time that we return only when the sync frequency in minutes is set to 1440 (which means 24 hours) and the daily_sync_time parameter was set using the Create a Connector or Modify a Connector request. |
schedule_type | The connector schedule configuration type. Supported values: auto, manual. |
status.setup_state | The current setup state of the connector. The available values are:incomplete - the setup config is incomplete, the setup tests never succeeded;connected - the connector is properly set up;broken - the connector setup config is broken. |
status.schema_status | Indicates the connector schema state. Possible values: blocked_on_capture - the schema is blocked for schema capturing; blocked_on_customer - the schema has been captured and is waiting for the user to review the schema;ready - the schema is ready. See the schema status guide for usage examples. |
status.sync_state | The current sync state of the connector. 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. |
status.rescheduled_for | The scheduled time for the next sync when sync_state is rescheduled. If schedule_type is manual, then the connector expects triggering the event at the designated time through the Sync Connector Data endpoint. |
update_state | The current data update state of the connector. 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. |
is_historical_sync | The boolean specifying whether the connector is at the historical data sync stage (also true for re-syncing 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. |
source_sync_details | The additional information about the connector's state. The format of this parameter is specific for each connector type. |
local_processing_agent_id | The unique identifier of the local processing agent in the Fivetran system. |
proxy_agent_id | The proxy agent ID. |
private_link_id | The private link ID. |
networking_method | Possible values: Directly, PrivateLink, SshTunnel, ProxyAgent |
API notes
In this API call, for the schema name field, the NetSuite SuiteAnalytics connector always returns the destination schema name set by the user in the connector setup form.
In this API call, for the schema name field, the Salesforce and Salesforce Sandbox connectors always return the destination schema name set by the user in the connector setup form.
In this API call, for the schema name field, the Oracle Fusion Cloud Applications connectors always return the destination schema name set by the user in the connector setup form.
Modify a Connector
Updates the information for an existing connector within your Fivetran account.
Request
PATCH https://api.fivetran.com/v1/connectors/{connector_id}
{
"paused": false,
"pause_after_trial": true,
"sync_frequency": 60,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"trust_certificates": true,
"run_setup_tests": true,
"schema_status": "blocked_on_capture",
"local_processing_agent_id": "lpa-id",
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "1",
"networking_method": "PrivateLink",
"config": {
"username": "newuser",
"password": "newpassword"
},
"auth": {
"client_access": {
"client_id": "my_client_id",
"client_secret": "my_client_secret"
},
"refresh_token": "my_refresh_token"
},
"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 the connector should be paused |
pause_after_trial | Specifies whether the connector should be paused after the free trial period has ended. |
sync_frequency | The connector sync frequency in minutes. The supported values are: 5, 15, 30, 60, 120, 180, 360, 480, 720, 1440. |
data_delay_sensitivity | Delay Threshold. Possible values: LOW, NORMAL, HIGH, CUSTOM. The default value NORMAL. CUSTOM is only available for customers using the Enterprise plan or above. |
data_delay_threshold | Custom sync delay notification threshold in minutes. The default value is 0. This parameter is only used when data_delay_sensitivity set to CUSTOM. |
daily_sync_time | 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. |
schema_status | Indicates the connector schema state. Possible values:blocked_on_capture - the schema is blocked for schema capturing;blocked_on_customer - the schema has been captured and is waiting for the user to review the schema;ready - the schema is ready.See the schema status guide for usage examples. |
config | The connector setup configuration. The format is specific for each connector. |
auth | The connector authorization settings. Can be used to authorize a connector using your external client credentials. The format is specific for each connector. |
trust_certificates | Specifies whether we should trust the certificate automatically. Applicable only for database connectors and when the config section is present and defined. The default value is FALSE. If a certificate is not trusted automatically, it has to be approved using the Certificates Management API Approve a connector certificate. |
trust_fingerprints | Specifies whether we should trust the SSH fingerprint automatically. Applicable only for database connectors. The default value is FALSE. If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a connector fingerprint. |
is_historical_sync | The boolean specifying whether the connector 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 connector 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. |
schedule_type | The connector schedule config type. Supported values: auto, manual. Lets you disable or enable an automatic data sync on a schedule. If you set this parameter to manual, the automatic data sync will be disabled, but you will be able to trigger the data sync using the Sync Connector Data endpoint. |
run_setup_tests | Specifies whether the setup tests should be run automatically. The default value is TRUE. |
local_processing_agent_id | The local processing agent ID refers to the controller created for the group the connection belongs to. If the value is specified, the system will try to associate the connection with an existing agent. |
proxy_agent_id | The proxy agent ID. |
private_link_id | The private link ID. |
networking_method | Possible values: Directly, PrivateLink, SshTunnel, ProxyAgent |
None of the paused, sync_frequency, daily_sync_time, config, auth, is_historical_sync, schedule_type, data_delay_sensitivity, data_delay_threshold parameters is required, but at least one of them has to be present and defined for a request of this type 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",
"paused": true,
"pause_after_trial": true,
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency": 60,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"local_processing_agent_id": "lpa-id",
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "1",
"networking_method": "PrivateLink",
"status": {
"setup_state": "incomplete",
"sync_state": "scheduled",
"update_state": "on_schedule",
"is_historical_sync": true,
"schema_status": "blocked_on_capture",
"tasks": [],
"warnings": []
},
"setup_tests": [{
"title": "Validate Login",
"status": "FAILED",
"message": "Invalid login credentials"
}],
"config": {
"username": "newuser",
"password": "******",
"api_token": "******",
"service_version": "0"
}
}
}
If the run_setup_tests parameter is set to FALSE in the request, then the response will not contain the setup_tests field.
Sync Connector Data
Triggers a 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 there is a data sync already in progress, that sync is immediately stopped and restarted. If the connector is paused, the data sync will be scheduled to be performed when the connector is re-enabled.
Request
POST https://api.fivetran.com/v1/connectors/{connector_id}/sync
{
"force": true
}
Payload parameters
| Name | Description |
|---|---|
force | If force is true and the connector is currently syncing, it will stop the sync and re-run it. If force is false, the connector will sync only if it isn't currently syncing. The default value is false. |
NOTE: If connector is paused it won't be triggered to sync.
Path parameters
| Name | Description |
|---|---|
connector_id (required) | The unique identifier for the connector within the Fivetran system. |
Payload
The request body can be empty, since the payload is optional. If the payload wasn't passed and the connector is currently syncing, nothing would be performed.
Response
HTTP 200 OK
{
"code": "Success",
"message": "Sync has been successfully triggered for connector with id 'connector_id1'"
}
Legacy Request
POST https://api.fivetran.com/v1/connectors/{connector_id}/force
NOTE: We renamed this endpoint and now use
syncas an action term to make our API contract match the terms on the Fivetran dashboard. This legacy endpoint is available for backward compatibility.
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 Data (Historical Sync)
Triggers a full historical sync of a connector or multiple schema tables within a connector.
Request
POST https://api.fivetran.com/v1/connectors/{connector_id}/resync
{
"scope": {
"schema1": ["table1", "table2"],
"schema2": ["table3", "table4", "table5"],
...,
"schemaN": ["table1", "table2", ..., "tableM"]
}
}
Path parameters
| Name | Description |
|---|---|
connector_id | The unique identifier for the connector within the Fivetran system. |
Payload
Call the endpoint without any payload to trigger a full historical re-sync for the connector.
The scope payload parameter is optional. It defines the scope of re-sync request. If you provide the scope parameter in the payload, the endpoint behaves exactly like the Re-sync connector table data endpoint.
NOTE: If you provide the
scopeparameter, it cannot be empty.
Payload parameters
| Name | Description |
|---|---|
scope | A map containing an array of tables to re-sync for each schema, must be non-empty. The parameter is optional. |
Response
HTTP 200 OK
{
"code": "Success",
"message": "Re-sync has been triggered successfully"
}
Re-sync Connector Table Data
Triggers a historical sync of all data for multiple schema tables 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 to be performed when the connector is re-enabled. If there is a data sync already in progress, we will try to complete it. If it fails, the request will be declined and the HTTP 409 Conflict error will be returned.
NOTE: If you want to trigger a historical sync for the entire connector, use the Re-sync Connector Data (Historical Sync) endpoint instead.
Request
POST https://api.fivetran.com/v1/connectors/{connector_id}/schemas/tables/resync
{
"schema1": ["table1", "table2"],
"schema2": ["table3", "table4", "table5"],
...,
"schemaN": ["table1", "table2", ..., "tableM"]
}
Payload
Payload parameters contain an array of tables for each schema.
| Name | Description |
|---|---|
connector_id (required) | The unique identifier for the connector within the Fivetran system. |
schema (required) | The database schema name within your destination. NOTE: The database schema is a different entity from the connector schema. |
table (required) | The table name within your database schema. |
Response
HTTP 200 OK
{
"code": "Success",
"message": "Re-sync has been triggered successfully"
}
Run connector setup tests
Runs the setup tests for an existing connector within your Fivetran account.
Request
POST https://api.fivetran.com/v1/connectors/{connector_id}/test
{
"trust_certificates": true,
"trust_fingerprints": 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 Approve a connector certificate. |
trust_fingerprints | Specifies whether we should trust the SSH fingerprint automatically. Applicable only for database connectors. The default value is FALSE. If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a connector fingerprint. |
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",
"paused": false,
"pause_after_trial": true,
"connected_by": "interment_burdensome",
"created_at": "2018-12-01T15:43:29.013729Z",
"succeeded_at": null,
"failed_at": null,
"sync_frequency":60,
"data_delay_sensitivity": "NORMAL",
"data_delay_threshold": 0,
"local_processing_agent_id": "lpa-id",
"proxy_agent_id": "proxy_agent_id",
"private_link_id": "1",
"networking_method": "PrivateLink",
"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 https://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 the connector schema config for an existing connector within your Fivetran account.
Request
GET https://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": true,
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"name_in_destination": "schema_1",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"supports_columns_config": true,
"sync_mode": "SOFT_DELETE",
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": true,
"hashed": true,
"enabled_patch_settings": {
"allowed": true
}
}
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_TABLE"
}
}
}
},
"schema_2": {
"name_in_destination": "schema_2",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"name_in_destination": "column_1",
"column_1": {
"enabled": false
}
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "OTHER",
"reason": "Permission denied"
}
}
}
}
}
}
}
Fields
| Name | Description | Possible Values |
|---|---|---|
enable_new_by_default | The boolean value specifying whether to enable new schemas and tables by default. Deprecated and will be removed in future API versions. | |
schema_change_handling | The value specifying how new source data is handled. See our Configure New Connectors during Setup documentation section for details. | ALLOW_ALL, ALLOW_COLUMNS, BLOCK_ALL |
schemas | The set of schemas within your connector schema config that are synced into the destination. | |
schema.name_in_destination | The schema name within your destination in accordance with Fivetran conventional rules. | |
schema.enabled | The boolean value specifying whether the sync for the schema into the destination is enabled. | |
schema.tables | The set of tables within your database schema config that are synced into the destination. | |
table.name_in_destination | The table name within your destination in accordance with Fivetran conventional rules. | |
table.enabled | The boolean value specifying whether the sync of table into the destination is enabled. | |
table.sync_mode | Beta This field appears in the response if the connector supports switching sync modes for tables. | SOFT_DELETE, LIVE, HISTORY. |
table.supports_columns_config | Beta This field indicates if the table supports columns configuration | |
table.enabled_patch_settings.allowed | The boolean value specifying whether the table.enabled property can be modified. | |
table.enabled_patch_settings.reason_code | The reason code indicating why the table.enabled property cannot be modified. This field appears in the response when the table.enabled_patch_settings.allowed property value is FALSE. | SYSTEM_TABLE, DELETED, OTHER. |
table.enabled_patch_settings.reason | The additional message indicating why the table.enabled property cannot be modified. This field appears in the response only when the table.enabled_patch_settings.reason_code value is OTHER. | |
table.columns | The set of columns within your table schema config that are synced into the destination. | |
column.name_in_destination | The column name within your destination in accordance with Fivetran conventional rules. | |
column.enabled | The boolean value specifying whether the sync of the column into the destination is enabled. | |
column.enabled_patch_settings.allowed | The boolean value specifying whether the column.enabled property can be modified. | |
column.enabled_patch_settings.reason_code | The reason code indicating why the column.enabled property cannot be modified. | SYSTEM_COLUMN, DELETED, OTHER. |
column.enabled_patch_settings.reason | The additional message indicating why the column.enabled property cannot be modified. This field only appears in the response when the column.enabled_patch_settings.reason_code property value is SYSTEM_COLUMN or OTHER. | |
column.hashed | The boolean value specifying whether a column is hashed or not. |
The response contains the difference between your selections and the schema config. The 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. For more information, see also the Connector Schema config section.
API notes
In this API call, for the NetSuite SuiteAnalytics connector, the schemas map field will always have a single entry with the netsuite key. For the schema.name_in_destination name field, the connector always returns the destination schema name set by the user in the connector setup form.
In this API call, for the Salesforce and Salesforce Sandbox connectors, the schemas map field will always have a single entry with the salesforece key. For the schema.name_in_destination name field, the connectors always return the destination schema name set by the user in the connector setup form.
For more information about this API call for the Oracle Fusion Cloud Applications connectors, see our Schema information documentation.
Connector Schema Config
The connector schema config stores the settings for schema, table, and column objects, and allows you to enable or disable it. If a schema, table, or column is enabled, Fivetran syncs the data for those objects to your destination.
A newly created connector doesn't have a schema config. Fivetran generates the schema config after the initial connector sync or after triggering the Reload a connector schema config endpoint. The config generated by default contains only schemas and tables.
There are the following possible modes depending on the schema_change_handling flag:
schema_change_handling = ALLOW_ALL- new schemas and tables that appear in the connector source are added to the config in the enabled state.schema_change_handling = ALLOW_COLUMNS- new schemas and tables that appear in the connector source are added to the config in the disabled state; new columns are enabled.schema_change_handling = BLOCK_ALL- new schemas, tables, and columns that appear in the connector source are added to the config in the disabled state.
Information about schemas and tables is always present in the config, but if the source produces new columns, they are excluded from sync only in BLOCK_ALL mode. In ALLOW_ALL and ALLOW_COLUMNS mode all columns under enabled schemas and tables are considered to be enabled even though they are not present in the config.
TIP: You can use the Retrieve Source Table Columns Config endpoint to see the schemas, tables, and columns as they appear in the source.
If you need to block a particular column from syncing, you will have to PATCH the connector config. The patched column is guaranteed to be returned to the API response no matter if the column is enabled or disabled.
Let's have a look at examples of different use-cases:
Event 1
You created a new connector and triggered the Reload a connector schema config endpoint. Suppose a connector source contains schema_1 and table_1 with column_1 and column_2.
The connector generates the following default config:
{
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
}
}
}
}
}
Event 2
A new table, table_2 with column_1, column_2 appears in the source.
What happens after the next connector sync:
The table_2 is added to the config in the enabled state. column_1, column_2 of table_2 are not added to the config. Data for column_1, column_2 of table_1 is synced to the destination. Data for column_1, column_2 of table_2 is synced to the destination.
{
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": true
}
}
}
}
}
Event 3
PATCH the connector config to set the schema_change_handling = ALLOW_COLUMNS property
{
"schema_change_handling": "ALLOW_COLUMNS",
"schemas": {
"schema_1": {
"enabled": true
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": true
}
}
}
}
}
Event 4
A new table, table_3, with column_1, column_2 appears in the source.
What happens after the next connector sync:
table_3 is added to the config in the disabled state. column_1, column_2 of table_3 are not added to the config. Data for column_1, column_2 of table_1 is synced to the destination. Data for column_1, column_2 of table_2 is synced to the destination. Data for table_3 with all its columns is blocked and excluded from sync.
{
"schema_change_handling": "ALLOW_COLUMNS",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true
},
"table_2": {
"enabled": true
},
"table_3": {
"enabled": false
}
}
}
}
}
Event 5
PATCH the connector config to disable column_1 of table_1
{
"schema_change_handling": "ALLOW_COLUMNS",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"columns": {
"column_1": {
"enabled": false,
"hashed": false
}
}
},
"table_2": {
"enabled": true
},
"table_3": {
"enabled": false
}
}
}
}
}
Event 6
New column_3 of table_1 appears in the source.
What happens after the next connector sync:
column_3 of table_1 is not added to the config. Data for column_2, column_3 of table_1 is synced to the destination. Data for column_1 of table_1 is blocked and excluded from sync. Data for column_1, column_2 of table_2 is synced to the destination. Data for table_3 with all its columns is blocked and excluded from sync.
{
"schema_change_handling": "ALLOW_COLUMNS",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"columns": {
"column_1": {
"enabled": false,
"hashed": false
}
}
},
"table_2": {
"enabled": true
},
"table_3": {
"enabled": false
}
}
}
}
}
Retrieve Source Table Columns Config
Returns the source table columns config for an existing connector within your Fivetran account.
Request
GET https://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. NOTE: The database schema is a different entity from the connector schema. |
table (required) | The table name within your source schema. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": false,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
}
}
}
}
The response contains an array of columns with the Fivetran sync settings for each column.
Fields
| Name | Description |
|---|---|
name_in_destination | The column name within your destination in accordance with Fivetran conventional rules. |
enabled | The boolean value specifying whether the sync of the column into the destination is enabled. |
hashed | The boolean value specifying whether a column should be hashed. |
column.enabled | The boolean value specifying whether the sync of the column into the destination is enabled. |
enabled_patch_settings.allowed | The boolean value specifying whether the column.enabled property can be modified. |
enabled_patch_settings.reason_code | The reason code indicating the reason why the column.enabled property cannot be modified: SYSTEM_COLUMN - the column is a system column; DELETED - the column was deleted in the source; OTHER - the column was excluded by the system for some reason. This field appears in the response when the enabled_patch_settings.allowed field value is FALSE. |
Fetching the data may take long time because we interact with the source. The response time depends on the connection to the source.
HTTP 400 Bad Request
{
"code": "InvalidInput",
"message": "We expected the connector's setup state ('status.setup_state') to be 'connected', but it was 'broken'. Please configure the connector and perform the connector setup tests."
}
The connector has a setup_state other than connected. Configure the connector and perform the connector setup tests.
Reload a Connector Schema Config
Reloads the 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 https://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 the standard config. NOTE: This does not exclude columns by default. | EXCLUDE, INCLUDE and PRESERVE. The default value is PRESERVE. |
The request body can be empty because it contains only one optional parameter exclude_mode that has value PRESERVE set by default.
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"name_in_destination": "schema_1",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": true,
"hashed": true,
"enabled_patch_settings": {
"allowed": true
}
}
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_TABLE"
}
}
}
},
"schema_2": {
"name_in_destination": "schema_2",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": false
}
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "OTHER",
"reason": "Permission denied"
}
}
}
}
}
}
}
Fields
| Name | Description | Possible Values |
|---|---|---|
enable_new_by_default | The boolean value specifying whether to enable new schemas and tables by default. Deprecated and will be removed in future API versions. | |
schema_change_handling | The value specifying how new source data is handled. See our Configure New Connectors during Setup documentation section for details. | ALLOW_ALL, ALLOW_COLUMNS, BLOCK_ALL |
schemas | The set of schemas within your connector schema config that are synced into the destination. | |
schema.name_in_destination | The schema name within your destination in accordance with Fivetran conventional rules. | |
schema.enabled | The boolean value specifying whether the sync for the schema into the destination is enabled. | |
schema.tables | The set of tables within your database schema config that are synced into the destination. | |
table.name_in_destination | The table name within your destination in accordance with Fivetran conventional rules. | |
table.enabled | The boolean value specifying whether the sync of table into the destination is enabled. | |
table.sync_mode | Beta This field appears in the response if the connector supports switching sync modes for tables. | SOFT_DELETE,LIVE, HISTORY. |
table.supports_columns_config | Beta This field indicates if the table supports columns configuration | |
table.enabled_patch_settings.allowed | The boolean value specifying whether the table.enabled property can be modified. | |
table.enabled_patch_settings.reason_code | The reason code indicating why the table.enabled property cannot be modified. This field appears in the response when the table.enabled_patch_settings.allowed property value is FALSE. | SYSTEM_TABLE, DELETED, OTHER. |
table.enabled_patch_settings.reason | The additional message indicating why the table.enabled property cannot be modified. This field appears in the response when the table.enabled_patch_settings.reason_code value is OTHER. | |
table.columns | The set of columns within your table schema config that are synced into the destination. | |
column.name_in_destination | The column name within your destination in accordance with Fivetran conventional rules. | |
column.enabled | The boolean value specifying whether the sync of the column into the destination is enabled. | |
column.enabled_patch_settings.allowed | The boolean value specifying whether the column.enabled property can be modified. | |
column.enabled_patch_settings.reason_code | The reason code indicating why the column.enabled property cannot be modified. | SYSTEM_COLUMN, DELETED, OTHER. |
column.enabled_patch_settings.reason | The additional message indicating why the column.enabled property cannot be modified. This field appears in the response when the column.enabled_patch_settings.reason_code property value is SYSTEM_COLUMN or OTHER. | |
column.hashed | The boolean value specifying whether a column is hashed or not. |
This method reloads the full schema from the connector's data source. 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 value, you can enable or disable syncing for all schemas and tables when reloading the connector schema config. When the default PRESERVE value is set, all selected schemas and tables in the standard config preserve their state. When the EXCLUDE value is set, the columns that haven't been modified by user yet are not excluded from the sync. Such columns may be present in the source and not displayed in the response, but they are considered to be included in the sync by default. If you enable syncing of their table, then all of these columns from the source will be synced in the next sync cycle. See also Troubleshooting: How to enable syncs only for the columns you need.
The response contains only the difference between your selections and the schema config. The 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. For more information, see also the Connector Schema config section.
API notes
In this API call, for the NetSuite SuiteAnalytics connector, the schemas map field will always have a single entry with the netsuite key. For the schema.name_in_destination name field, the connector always returns the destination schema name set by the user in the connector setup form.
In this API call, for the Salesforce and Salesforce Sandbox connectors, the schemas map field will always have a single entry with the salesforce key. For the schema.name_in_destination name field, the connectors always return the destination schema name set by the user in the connector setup form.
For more information about this API call for the Oracle Fusion Cloud Applications connectors, see our Schema information documentation.
HTTP 400 Bad Request
{
"code": "InvalidInput",
"message": "We expected the connector's setup state ('status.setup_state') to be 'connected', but it was 'broken'. Please configure the connector and perform the connector setup tests."
}
The connector has a setup_state other than connected. Configure the connector and perform the connector setup tests.
Create a Connector Schema Config Beta
Creates a schema config for an existing connector within your Fivetran account in case the connector doesn't have it yet (before the schema capture at the initial sync or schema reload). The endpoint allows to specify any schema/table/column settings. During the initial sync, all elements that are not represented in the source will be marked as Deleted from source and disabled from sync. It returns HTTP 409 Conflict if the connector already has non-empty schema settings (at least one schema was captured or configured).
Request
POST https://api.fivetran.com/v1/connectors/{connector_id}/schemas
{
"schema_change_handling": "BLOCK_ALL",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"sync_mode": "HISTORY"
},
"table_2": {
"enabled": true,
"columns": {
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"enabled": true,
"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 | Possible values |
|---|---|---|
schema_change_handling | The value specifying how new source data is handled. See our Configure New Connectors during Setup documentation section for details. | ALLOW_ALL, ALLOW_COLUMNS, BLOCK_ALL |
schema.enabled | (Required) The boolean value specifying whether the sync for the schema into the destination is enabled. | |
table.enabled | (Required) The boolean value specifying whether the sync of table into the destination is enabled. | |
table.sync_mode | Beta This field can only be used in the request body if the connector supports switching of the table sync modes and the specified sync_mode value. | SOFT_DELETE, LIVE, HISTORY. |
column.enabled | (Required) The boolean value specifying whether the sync of the column into the destination is enabled. | |
column.hashed | The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"sync_mode": "HISTORY"
},
"table_2": {
"enabled": true,
"columns": {
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"enabled": true,
"hashed": true
}
}
}
}
},
"schema_2": {
"enabled": false
}
}
}
}
The response contains the exact settings that were passed in request. After the initial sync, when the connector captures the schema from the source, we try to apply the specified settings on the actual schema from the source. In case some table or column are not allowed to be excluded, we ignore the settings for the relevant entity.
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 https://api.fivetran.com/v1/connectors/{connector_id}/schemas
{
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"sync_mode": "HISTORY"
},
"table_2": {
"enabled": false,
"columns": {
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"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 | Possible values |
|---|---|---|
schema_change_handling | The value specifying how new source data is handled. See our Configure New Connectors during Setup documentation section for details. | ALLOW_ALL, ALLOW_COLUMNS, BLOCK_ALL |
schema.enabled | The boolean value specifying whether the sync for the schema into the destination is enabled. | |
table.enabled | The boolean value specifying whether the sync of table into the destination is enabled. | |
table.sync_mode | Beta This field can only be used in the request body if the connector supports switching table sync modes and supports the provided sync_mode value. | SOFT_DELETE, LIVE, HISTORY. |
column.enabled | The boolean value specifying whether the sync of the column into the destination is enabled. | |
column.hashed | The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schema_change_handling": "ALLOW_ALL"
"schemas": {
"schema_1": {
"name_in_destination": "schema_1",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "HISTORY",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": true,
"hashed": true,
"enabled_patch_settings": {
"allowed": true
}
}
}
}
}
},
"schema_2": {
"name_in_destination": "schema_2",
"enabled": false,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_TABLE"
}
}
}
}
}
}
}
For backward compatibility, the response may contain the enable_new_by_default boolean field. It indicates if the sync for new schemas and tables is enabled by default. The value is true if you specify ALLOW_ALL as the value of schema_change_handling. In the future API versions, we may remove this field.
The response contains only the difference between your selections and the schema config. The 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. For more information, see also the Connector Schema config section.
The connector schema config request processing may be time-consuming. Hence, when you send a request, the previous one may still be processed by the backend. In that case, you get a 409 Conflict response:
HTTP 409 Conflict
{
"code": "IllegalState",
"message": "Entity was updated/deleted or is being updated/deleted by another transaction. Try to re-submit your request."
}
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 https://api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}
{
"enabled": true,
"tables": {
"table_1": {
"enabled": true,
"sync_mode": "HISTORY"
},
"table_2": {
"enabled": false,
"columns": {
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"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 | Possible values |
|---|---|---|
enabled | The boolean value specifying whether the sync for the schema into the destination is enabled. | |
table.enabled | The boolean value specifying whether the sync of table into the destination is enabled. | |
table.sync_mode | Beta This field can only be used in the request body if the connector supports switching table sync modes and supports the provided sync_mode value. | SOFT_DELETE, LIVE, HISTORY. |
column.enabled | The boolean value specifying whether the sync of the column into the destination is enabled. | |
column.hashed | The boolean value specifying whether the column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"name_in_destination": "schema_1",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "HISTORY",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": true,
"hashed": true,
"enabled_patch_settings": {
"allowed": true
}
}
}
}
}
},
"schema_2": {
"name_in_destination": "schema_2",
"enabled": false,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_TABLE"
}
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. The 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. For more information, see also the Connector Schema config section.
API notes
In this API call, the NetSuite SuiteAnalytics connector always returns the schema name as netsuite.
In this API call, the Salesforce and Salesforce Sandbox connectors always return the schema name as salesforce.
For more information about this API call for the Oracle Fusion Cloud Applications connectors, see our Schema information documentation.
Modify a Connector Table Config
Updates the table config within your database schema for an existing connector within your Fivetran account.
Request
PATCH https://api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}/tables/{table}
{
"enabled": false,
"sync_mode": "HISTORY",
"columns": {
"column_2": {
"enabled": true,
"hashed": false
},
"column_3": {
"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 | Possible values |
|---|---|---|
enabled | The boolean value specifying whether the sync for the table into the destination is enabled. | |
sync_mode | Beta This field can only be used in the request body if the connector supports switching table sync modes and supports provided sync_mode value. | SOFT_DELETE, LIVE, HISTORY. |
column.enabled | The boolean value specifying whether the sync of the column into the destination is enabled. | |
column.hashed | The boolean value specifying whether the column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"name_in_destination": "schema_1",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "HISTORY",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": true,
"hashed": true,
"enabled_patch_settings": {
"allowed": true
}
}
}
}
}
},
"schema_2": {
"name_in_destination": "schema_2",
"enabled": false,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_TABLE"
}
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. The 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. For more information, see also the Connector Schema config section.
Modify a Connector Column Config
Updates the column config within your table for an existing connector within your Fivetran account.
Request
PATCH https://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 the sync for the column into the destination is enabled. |
hashed | The boolean value specifying whether a column should be hashed. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"enable_new_by_default": true,
"schema_change_handling": "ALLOW_ALL",
"schemas": {
"schema_1": {
"name_in_destination": "schema_1",
"enabled": true,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
},
"columns": {
"column_1": {
"name_in_destination": "column_1",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_COLUMN",
"reason": "The column does not support exclusion as it is a Primary Key"
}
},
"column_2": {
"name_in_destination": "column_2",
"enabled": true,
"hashed": false,
"enabled_patch_settings": {
"allowed": true
}
},
"column_3": {
"name_in_destination": "column_3",
"enabled": true,
"hashed": true,
"enabled_patch_settings": {
"allowed": true
}
}
}
}
}
},
"schema_2": {
"name_in_destination": "schema_2",
"enabled": false,
"tables": {
"table_1": {
"name_in_destination": "table_1",
"enabled": true,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": true,
"enabled_patch_settings": {
"allowed": true
}
},
"table_2": {
"name_in_destination": "table_2",
"enabled": false,
"sync_mode": "SOFT_DELETE",
"supports_columns_config": false,
"enabled_patch_settings": {
"allowed": false,
"reason_code": "SYSTEM_TABLE"
}
}
}
}
}
}
}
The response contains only the difference between your selections and the schema config. The 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. For more information, see also the Connector Schema config section.
Retrieve Connector State
This endpoint returns the actual connector state if the connector exist. This endpoint is only supported for Function and Connector SDK connectors.
Request
GET https://api.fivetran.com/v1/connectors/{connector_id}/state
Path parameters
| Name | Description |
|---|---|
connector_id (required) | The unique identifier for the connector within your Fivetran account. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"state": {
"cursor": "2023-06-16T01:17:47.710228"
}
}
}
Fields
| Name | Description |
|---|---|
| state | Contains the connector state values as JSON. |
HTTP 400 BAD REQUEST
The connector state doesn't exist.
HTTP 404 NOT_FOUND
Connector with the specified connector_id doesn't exist.
HTTP 405 METHOD_NOT_ALLOWED
This connector is not a function connector.
Update Connector State
This endpoint allows you to modify the connector state. To update the state, you should pause your connector first. To modify the connector state, do the following:
- Pause connector using Modify a Connector endpoint (set
pausedtotrue). - Update the state by using the Update Connector State endpoint.
- Unpause the connector by setting the
pausedparameter tofalsein the Modify a Connector endpoint request.
This endpoint is only supported for Function and Connector SDK connectors.
Request
PATCH https://api.fivetran.com/v1/connectors/{connector_id}/state
{
"state": {
"cursor": "2023-06-16T01:17:47.710228"
}
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) | The unique identifier for the connector within your Fivetran account. |
Payload parameters
| Name | Description |
|---|---|
| state | Contains updated state object as JSON. |
Response
HTTP 200 OK
{
"code": "Success",
"data": {
"state": {
"cursor": "2023-06-16T01:17:47.710228"
}
}
}
Fields
| Name | Description |
|---|---|
| state | Contains the updated connector state value(s). |
HTTP 400 BAD REQUEST
The connector state doesn't exist.
HTTP 404 NOT_FOUND
Connector with the specified connector_id doesn't exist.
HTTP 405 METHOD_NOT_ALLOWED
This connector is not a function connector.
HTTP 409 CONFLICT
Connector cannot be updated because the sync is in progress.
Delete Blocked Column
Marks for deletion a blocked column from your table in the destination of an existing connector within your Fivetran account. The column is dropped from the destination on the next sync.
Request
DELETE https://api.fivetran.com/v1/connectors/{connector_id}/schemas/{schema}/tables/{table}/columns/{column}
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. |
Response
HTTP 200 OK
The response contains information that the column was deleted.
HTTP 404 NOT_FOUND
- Connector with the specified
connector_iddoesn't exist. - Schema with the specified
schemadoes not exist. - Table with the specified
tabledoes not exist. - Column with the specified
columndoes not exist.
HTTP 409 CONFLICT Column is not in the blocked state.
Delete Blocked Columns
Marks for deletion multiple blocked column from your tables in schemas in the destination of an existing connector within your Fivetran account. The columns are dropped from the destination on the next sync.
REQUEST
POST https://api.fivetran.com/v1/connectors/{connector_id}/schemas/drop-columns
{
"schemas": {
"schema_name1": {
"tables": {
"table_name1": [
"column_name1",
"column_name2"
],
"table_name2": [
"column_name1",
"column_name2"
]
},
"schema_name2": {
"tables": {
"table_name1": [
"column_name1",
"column_name2"
],
"table_name2": [
"column_name1",
"column_name2"
]
}
}
}
}
}
Path parameters
| Name | Description |
|---|---|
connector_id (required) | The unique identifier for the connector within the Fivetran system. |
Response
HTTP 200 OK
The response contains information that the column was deleted
HTTP 400 BAD_REQUEST
- The
schemasfield is empty in the request. - The
tablesfield is empty in the request. - The
column_namevalues are not provided in the request.
HTTP 404 NOT_FOUND
- Connector with the specified
connector_iddoesn't exist. - Schema with the specified
schemadoes not exist. - Table with the specified
tabledoes not exist. - Column with the specified
columndoes not exist.
HTTP 409 CONFLICT Column is not in the blocked state.