Create a Connection
Creates a new connection within a specified group in your Fivetran account. Runs setup tests and returns testing results.
IMPORTANT: The
destination_schema_namesfield will soon become a required field. Make sure to include it in your API requests when creating new connections to prevent future disruptions. IMPORTANT: If you want to get the fingerprint details, do not settrust_fingerprintstotruewhen you create a connection with our REST API. We can only provide the fingerprint details through the failed SSH Tunnel Connection setup test. For a full walkthrough, see Get Connection Fingerprint Details.
Request schema
Header parameters
HTTP: basicAuth
HTTP AuthorizationScheme: basic
Request
The unique identifier of the destination group to create the connection in. Retrieve group IDs from the List All Groups endpoint.
The connector name within the Fivetran system
Specifies whether we should trust the certificate automatically during setup tests. The default value is FALSE. This parameter only affects the behavior of setup tests and does not persist in the connection configuration. When using the PATCH endpoint to update a connection, this parameter must be combined with run_setup_tests=true and at least one persistent configuration parameter (e.g., sync_frequency, paused, config, auth). If you only want to run setup tests with automatic certificate trust, use the POST /v1/connections/{connectionId}/test endpoint instead. If a certificate is not trusted automatically during testing, it has to be approved with Certificates Management API Approve a destination certificate.
Specifies whether we should trust the SSH fingerprint automatically during setup tests. The default value is FALSE. This parameter only affects the behavior of setup tests and does not persist in the connection configuration. When using the PATCH endpoint to update a connection, this parameter must be combined with run_setup_tests=true and at least one persistent configuration parameter (e.g., sync_frequency, paused, config, auth). If you only want to run setup tests with automatic fingerprint trust, use the POST /v1/connections/{connectionId}/test endpoint instead. If a fingerprint is not trusted automatically during testing, it has to be approved with Certificates Management API Approve a destination fingerprint.
Specifies whether the setup tests should be run automatically after updating the connection. The default value is TRUE. When using this parameter in a PATCH request, you must also include at least one persistent configuration parameter (e.g., sync_frequency, paused, config, auth). This parameter can be combined with trust_certificates or trust_fingerprints to automatically approve certificates/fingerprints during the test run. To run setup tests without making configuration changes, use the POST /v1/connections/{connectionId}/test endpoint instead.
Specifies whether the connection is paused
Specifies whether the connection should be paused after the free trial period has ended
The connection sync frequency in minutes
The level of data delay notification threshold. Possible values: LOW, NORMAL, HIGH, CUSTOM, SYNC_FREQUENCY. The default value NORMAL. CUSTOM is only available for customers using the Enterprise plan or above.
Custom sync delay notification threshold in minutes. The default value is 0. This parameter is only used when data_delay_sensitivity set to CUSTOM.
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
The connection schedule configuration type. Supported values: auto, manual
The URI on your site we redirect the end user to after successful setup. The URI must start with the https or http prefix.
An optional parameter that lets you hide the embedded setup guide in the Connect Card.
An optional parameter that lets you show all fields on Connect Card including those that are hidden by default for certain connectors.
The unique identifier for the proxy agent within the Fivetran system
The unique identifier for the self-served private link that is used by the connection
The unique identifier for the hybrid deployment agent within the Fivetran system. If not specified, the agent ID from the destination will be used
Snowflake's virtual warehouse used in the connection
Defines how you want the schema names to appear in your destination.
The available values are:
- FIVETRAN_NAMING - Use Fivetran naming conventions to simplify and standardize the schema, table and column names in the destination.
- SOURCE_NAMING - Preserve source schema table and column names in the destination.
You can modify your selection only before the initial sync. Learn more in our documentation
IMPORTANT: This field will soon become a required field. Make sure to include it in your API requests when creating new connections to prevent future disruptions.
Your 15five API key.
Destination schema name. Schema name is permanent and cannot be changed after connection creation
POST /v1/connections HTTP/1.1 Accept: application/json;version=2 Authorization: BasicContent-Type: application/json Host: api.fivetran.com Content-Length: 860 { "group_id": "group_id", "service": "15five", "trust_certificates": true, "trust_fingerprints": true, "run_setup_tests": true, "paused": false, "pause_after_trial": false, "sync_frequency": 1440, "data_delay_sensitivity": "NORMAL", "data_delay_threshold": 0, "daily_sync_time": "14:00", "schedule_type": "auto", "connect_card_config": { "redirect_uri": "https://your.site/path", "hide_setup_guide": true, "all_fields": true }, "proxy_agent_id": "proxy_agent_id", "private_link_id": "private_link_id", "networking_method": "Directly", "hybrid_deployment_agent_id": "hybrid_deployment_agent_id", "destination_configuration": { "virtual_warehouse": "virtual_warehouse" }, "destination_schema_names": "FIVETRAN_NAMING", "config": { "api_key": "your_15five_api_key", "schema": "schema_name" } }
Responses
201
Response status code
Response status text
The unique identifier of this connection. Use this value as the connectionId path parameter when calling other Connections API endpoints, such as Retrieve Connection Details or Sync Connection Data.
The connector name within the Fivetran system
The name used both as the connection's name within the Fivetran system and as the source schema's name within your destination
Specifies whether the connection is paused
The collection of tasks for the connection
A machine-readable identifier for the warning type (for example: resync_table_warning). Use this value to programmatically detect and respond to specific connection conditions.
A human-readable label describing the warning. For example: Resync Table Warning.
The collection of warnings for the connection
A machine-readable identifier for the warning type (for example: resync_table_warning). Use this value to programmatically detect and respond to specific connection conditions.
A human-readable label describing the warning. For example: Resync Table Warning.
The current setup state of the connection. The available values are:
- incomplete - the setup config is incomplete, the setup tests never succeeded
- connected - the connection is properly set up
- broken - the connection setup config is broken.
Schema status. Returned only for connectors that support Universal Column Masking flow.
The current sync state of the connection. The available values are:
- scheduled - the sync is waiting to be run
- syncing - the sync is currently running
- paused - the sync is currently paused
- rescheduled - the sync is waiting until more API calls are available in the source service.
The current data update state of the connection. The available values are:
- on_schedule - the sync is running smoothly, no delays
- delayed - the data is delayed for a longer time than expected for the update.
The boolean specifying whether the connection should be triggered to re-sync all historical data. If you set this parameter to TRUE, a historical sync starts immediately. If a sync is currently running, it's canceled and restarted as a historical sync. All subsequent syncs after the historical sync completes will be incremental. If the value is FALSE or not specified, the connection doesn't re-sync historical data. This parameter is automatically reset to FALSE once the historical sync is completed.
The UTC timestamp of the next scheduled sync attempt. Non-null only when sync_state is "rescheduled". If schedule_type is manual, the connection expects the sync to be triggered at the designated time through the Sync Connection Data endpoint.
The unique identifier of the destination group this connection belongs to. Use this value with the List All Groups or Retrieve Group Details endpoints.
The connector version within the Fivetran system
The unique identifier of the user who created this connection. null if the connection was created programmatically without a user context. Use this value with the Retrieve User Details endpoint.
The timestamp of the time the connection was created in your account
The UTC timestamp of the most recent successful sync. null if the connection has never completed a successful sync.
The UTC timestamp of the most recent failed sync. null if the connection has never experienced a sync failure.
Specifies whether the connection should be paused after the free trial period has ended
The connection sync frequency in minutes
Custom sync delay notification threshold in minutes. The default value is 0. This parameter is only used when data_delay_sensitivity set to CUSTOM.
The level of data delay notification threshold. Possible values: LOW, NORMAL, HIGH, CUSTOM, SYNC_FREQUENCY. The default value NORMAL. CUSTOM is only available for customers using the Enterprise plan or above.
The unique identifier for the self-served private link that is used by the connection
The unique identifier for the proxy agent within the Fivetran system
The daily sync start time, in HH:MM format (UTC), at which the connection syncs. Returned only when sync_frequency is 1440 and daily_sync_time was explicitly set. null otherwise.
The connection schedule configuration type. Supported values: auto, manual
Setup tests results for this connection
A human-readable name for the setup test step. For example: Validate Login, Test Connection, Check Permissions.
The result of the individual setup test step. Possible values: PASSED, FAILED, SKIPPED.
The result message for the setup test step. For example: Invalid login credentials.
Additional diagnostic information about the setup test result. Populated when the status is FAILED and more context is available beyond the message.
The additional information about the connection's state. The format of this parameter is specific for each connection type
A short-lived JWT that authorizes the end user to configure this connection via the Connect Card interface. Use the uri field directly to redirect users — it already embeds this token. If you need to construct your own URL, pass this value as the auth query parameter to https://fivetran.com/connect-card/setup.
The complete URL to redirect the end user to in order to authorize the connection. It embeds the auth token, redirect URI, and setup guide visibility as query parameters. Redirect the user directly to this address.
The URI on your site we redirect the end user to after successful setup. The URI must start with the https or http prefix.
An optional parameter that lets you hide the embedded setup guide in the Connect Card.
An optional parameter that lets you show all fields on Connect Card including those that are hidden by default for certain connectors.
The unique identifier for the hybrid deployment agent within the Fivetran system. If not specified, the agent ID from the destination will be used
Snowflake's virtual warehouse used in the connection
Defines how schema names appear in your destination.
The possible values are:
- FIVETRAN_NAMING - Uses Fivetran naming conventions to simplify and standardize the schema, table and column names in the destination.
- SOURCE_NAMING - Preserves source schema table and column names in the destination.
Your 15five API key.
{ "code": "Success", "message": "Connection has been created", "data": { "id": "connection_id", "service": "15five", "schema": "schema.table", "paused": false, "status": { "tasks": [ { "code": "resync_table_warning", "message": "Resync Table Warning", "details": "string" } ], "warnings": [ { "code": "resync_table_warning", "message": "Resync Table Warning", "details": "string" } ], "setup_state": "connected", "schema_status": "ready", "sync_state": "scheduled", "update_state": "delayed", "is_historical_sync": false, "rescheduled_for": "2024-12-01T15:43:29.013729Z" }, "group_id": "group_id", "service_version": 0, "connected_by": "priceless_odour", "created_at": "2023-12-01T15:43:29.013729Z", "succeeded_at": "2024-03-17T12:31:40.870504Z", "failed_at": "2024-04-01T18:13:25.043659Z", "pause_after_trial": false, "sync_frequency": 1440, "data_delay_threshold": 0, "data_delay_sensitivity": "NORMAL", "private_link_id": "link_id", "networking_method": "Directly", "proxy_agent_id": "agent_id", "daily_sync_time": "14:00", "schedule_type": "auto", "setup_tests": [ { "title": "Validate Login", "status": "FAILED", "message": "Invalid login credentials.", "details": "Authentication failed (401 Unauthorized). Verify the provided credentials and permissions." } ], "source_sync_details": {}, "connect_card": { "token": "eyJ0e...", "uri": "https://fivetran.com/connect-card/setup?redirect_uri=https://your.site/path&auth=eyJ0e...&hide_setup_guide=true" }, "connect_card_config": { "redirect_uri": "https://your.site/path", "hide_setup_guide": true, "all_fields": true }, "hybrid_deployment_agent_id": "agent_id", "destination_configuration": { "virtual_warehouse": "virtual_warehouse" }, "destination_schema_names": "FIVETRAN_NAMING", "config": { "api_key": "your_15five_api_key" } } }