Destination Managementlink
IMPORTANT: Destinations and groups are mapped 1:1 to each other. We do this mapping using the group's
id
value that we automatically generate when you create a group using our REST API, and the destination'sgroup_id
value that you specify when you create a destination using our REST API. This means that if you use our REST API to create a destination, you must create a group in your Fivetran account before you can create a destination in it.When you create a destination in your Fivetran dashboard, we automatically create a group and assign a value to its
id
and a destination with the samegroup_id
value, which is unique in your Fivetran account. The group'sname
corresponds to the Destination name you specify in your Fivetran dashboard when creating the destination in your Fivetran dashboard.
REST API supports the following destination management actions:
- Create a destination
- Retrieve destination details
- Modify a destination
- Run destination setup tests
- Delete a destination
Create a Destinationlink
Creates a new destination within a specified group in your Fivetran account.
Requestlink
POST https://api.fivetran.com/v1/destinations
{
"group_id":"target_group_id",
"service":"snowflake",
"region":"GCP_US_EAST4",
"time_zone_offset":"-5",
"daylight_saving_time_enabled": true,
"local_processing_agent_id": "lpa-id",
"config":{
"host":"your-account.snowflakecomputing.com",
"port":443,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"123456"
}
}
Payload parameterslink
Name | Description | Possible Values |
---|---|---|
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 destination type within the Fivetran system. | Possible destination types |
region | Data processing location. This is where Fivetran will operate and run computation on data. | GCP_US_EAST4 , GCP_US_WEST1 , GCP_EUROPE_WEST3 , GCP_AUSTRALIA_SOUTHEAST1 , GCP_NORTHAMERICA_NORTHEAST1 , GCP_EUROPE_WEST2 , GCP_ASIA_SOUTHEAST1 , AWS_US_EAST_1 , AWS_US_EAST_2 , AWS_US_WEST_2 , AWS_AP_SOUTHEAST_2 , AWS_EU_CENTRAL_1 , AWS_EU_WEST_1 , AWS_EU_WEST_2 , AZURE_EASTUS2 , AZURE_AUSTRALIAEAST , GCP_ASIA_SOUTH1 . The default value is GCP_US_EAST4 . |
time_zone_offset (required) | Determines the time zone for the Fivetran sync schedule. | -11, 10 ... ,0 , ... +11, +12 . |
daylight_saving_time_enabled | Shift my UTC offset with daylight saving time (US Only) | |
local_processing_agent_id | Local processing agent id reffers to the controller created for the group the destination belongs to. If the value is set the system will try to associate the destination with an existing agent. | |
config (required) | Destination setup configuration. The format is specific for each destination. | |
trust_certificates | Specifies whether we should trust the certificate automatically. The default value is FALSE . If a certificate is not set to be trusted automatically, it has to be approved using the Approve a Destination Certificate endpoint. | |
trust_fingerprints | Specifies whether we should trust the SSH fingerprint automatically. The default value is FALSE . If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a destination fingerprint. | |
run_setup_tests | The boolean that specifies whether the setup tests should be run automatically. | true or false . The default value is true (tests run automatically by default). |
Responselink
HTTP 201 Created
{
"code":"Success",
"message":"Destination has been created",
"data":{
"id":"decent_dropsy",
"group_id":"decent_dropsy",
"service":"snowflake",
"region":"GCP_US_EAST4",
"time_zone_offset":"-5",
"daylight_saving_time_enabled": true,
"local_processing_agent_id": "lpa-id",
"setup_status":"connected",
"setup_tests":[
{
"title":"Host Connection",
"status":"PASSED",
"message":""
},
{
"title":"Database Connection",
"status":"PASSED",
"message":""
},
{
"title":"Permission Test",
"status":"PASSED",
"message":""
}
],
"config":{
"host":"your-account.snowflakecomputing.com",
"port":443,
"database":"fivetran",
"auth": "PASSWORD",
"user":"fivetran_user",
"password":"******"
}
}
}
NOTE: You can use the new destination configuration response format for the following destinations:
If the setup tests pass successfully, the setup_status
field will contain connected
.
HTTP 201 Created
{
"code":"Success",
"message":"Destination has been created",
"data":{
"id":"decent_dropsy",
"group_id":"decent_dropsy",
"service":"snowflake",
"region":"GCP_US_EAST4",
"time_zone_offset":"-5",
"daylight_saving_time_enabled": true,
"setup_status":"incomplete",
"local_processing_agent_id": "lpa-id",
"setup_tests":[
{
"title":"Host Connection",
"status":"FAILED",
"message":"Host address is private and not accessible via the internet"
}
],
"config":{
"host":"your-account.snowflakecomputing.com",
"port":443,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"******"
}
}
}
If the tests fail, the setup_status
field will display incomplete
.
HTTP 201 Created
{
"code":"Success",
"message":"Destination has been created",
"data":{
"id":"decent_dropsy",
"group_id":"decent_dropsy",
"service":"snowflake",
"region":"GCP_US_EAST4",
"time_zone_offset":"-5",
"daylight_saving_time_enabled": true,
"setup_status":"incomplete",
"config":{
"host":"your-account.snowflakecomputing.com",
"port":443,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"******"
}
}
}
If run_setup_tests
is set to false
in the request, the response will not contain the setup_tests
field and the setup_status
field will always contain incomplete
.
Retrieve destination detailslink
Returns a destination object if a valid identifier was provided.
Requestlink
GET https://api.fivetran.com/v1/destinations/{destination_id}
Path parameterslink
Name | Description |
---|---|
destination_id (required) | The unique identifier for the destination within your Fivetran account. |
Responselink
HTTP 200 OK
{
"code":"Success",
"data":{
"id":"decent_dropsy",
"group_id":"decent_dropsy",
"service":"snowflake",
"region":"GCP_US_EAST4",
"time_zone_offset":"-5",
"daylight_saving_time_enabled": true,
"local_processing_agent_id": "lpa-id",
"setup_status":"connected",
"config":{
"host":"your-account.snowflakecomputing.com",
"port":443,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"******"
}
}
}
NOTE: You can use the new destination configuration response format for the following destinations:
Modify a Destinationlink
Updates information for an existing destination within your Fivetran account.
Requestlink
PATCH https://api.fivetran.com/v1/destinations/{destination_id}
Path parameterslink
Name | Description |
---|---|
destination_id (required) | The unique identifier for the destination within your Fivetran account. |
{
"region":"GCP_AUSTRALIA_SOUTHEAST1",
"time_zone_offset":"+10",
"local_processing_agent_id": "lpa-id",
"config":{
"host":"your-account.snowflakecomputing.com",
"port":1433,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"123456"
}
}
Payload parameterslink
Name | Description | Possible Values |
---|---|---|
region | Data processing location. This is where Fivetran will operate and run computation on data. | GCP_US_EAST4 , GCP_US_WEST1 , GCP_EUROPE_WEST3 , GCP_AUSTRALIA_SOUTHEAST1 , GCP_NORTHAMERICA_NORTHEAST1 , GCP_EUROPE_WEST2 , GCP_ASIA_SOUTHEAST1 , AWS_US_EAST_1 , AWS_US_EAST_2 , AWS_US_WEST_2 , AWS_AP_SOUTHEAST_2 , AWS_EU_CENTRAL_1 , AWS_EU_WEST_1 , AWS_EU_WEST_2 , AZURE_EASTUS2 , AZURE_AUSTRALIAEAST , GCP_ASIA_SOUTH1 . |
time_zone_offset | Determines the time zone for the Fivetran sync schedule. | -11, 10 ... ,0 , ... +11, +12 |
daylight_saving_time_enabled | Shift my UTC offset with daylight saving time (US Only) | |
config | Destination setup configuration. The format is specific for each destination. | |
trust_certificates | Specifies whether we should trust the certificate automatically. The default value is FALSE . If a certificate is not trusted automatically, it has to be approved with Certificates Management API Approve a destination certificate. | |
trust_fingerprints | Specifies whether we should trust the SSH fingerprint automatically. The default value is FALSE . If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a destination fingerprint. | |
run_setup_tests | The boolean that specifies whether the setup tests should be run automatically. | true or false . The default value is true (tests run automatically by default). |
local_processing_agent_id | The ID of the local processing agent that is used for the hybrid deployment. | A specified value will update the local processing agent. An explicit null value will disable the hybrid deployment, which is only possible if there are no associated connectors. |
None of the region
, time_zone_offset
, and config
parameters are required, but at least one of them has to be specified for the Modify a Destination request to succeed.
Responselink
HTTP 200 OK
{
"code":"Success",
"message":"Destination has been updated",
"data":{
"id":"decent_dropsy",
"group_id":"decent_dropsy",
"service":"snowflake",
"region":"GCP_AUSTRALIA_SOUTHEAST1",
"time_zone_offset":"+10",
"daylight_saving_time_enabled": true,
"local_processing_agent_id": "lpa-id",
"setup_status":"connected",
"setup_tests":[
{
"title":"Host Connection",
"status":"PASSED",
"message":""
},
{
"title":"Database Connection",
"status":"PASSED",
"message":""
},
{
"title":"Permission Test",
"status":"PASSED",
"message":""
}
],
"config":{
"host":"your-account.snowflakecomputing.com",
"port":1433,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"******"
}
}
}
NOTE: You can use the new destination configuration response format for the following destinations:
If the setup tests pass successfully, the setup_status
field will contain connected
.
HTTP 200 OK
{
"code":"Success",
"message":"Destination has been updated",
"data":{
"id":"decent_dropsy",
"group_id":"decent_dropsy",
"service":"snowflake",
"region":"GCP_AUSTRALIA_SOUTHEAST1",
"time_zone_offset":"+10",
"daylight_saving_time_enabled": true,
"setup_status":"broken",
"setup_tests":[
{
"title":"Host Connection",
"status":"FAILED",
"message":"Host address is private and not accessible via the internet"
}
],
"config":{
"host":"your-account.snowflakecomputing.com",
"port":1443,
"database":"fivetran",
"auth":"PASSWORD",
"user":"fivetran_user",
"password":"******"
}
}
}
If the setup tests fail, the setup_status
field will display broken
.
Run destination setup testslink
Runs the setup tests for an existing destination within your Fivetran account.
Requestlink
POST https://api.fivetran.com/v1/destinations/{destination_id}/test
{
"trust_certificates": true,
"trust_fingerprints": true
}
Path parameterslink
Name | Description |
---|---|
destination_id (required) | The unique identifier for the destination within your Fivetran account. |
Payload parameterslink
Name | Description |
---|---|
trust_certificates | Specifies whether we should trust the certificate automatically. The default value is FALSE . If a certificate is not trusted automatically, it has to be approved with Certificates Management API Approve a destination certificate. |
trust_fingerprints | Specifies whether we should trust the SSH fingerprint automatically. The default value is FALSE . If a fingerprint is not trusted automatically, it has to be approved with Certificates Management API Approve a destination fingerprint. |
Responselink
HTTP 200 OK
{
"code": "Success",
"message": "Setup tests have been completed",
"data": {
"id": "destination_id",
"group_id": "group_id",
"service": "postgres_rds_warehouse",
"region": "GCP_US_EAST4",
"time_zone_offset": "-8",
"daylight_saving_time_enabled": true,
"local_processing_agent_id": "lpa-id",
"setup_status": "incomplete",
"setup_tests": [
{
"title": "Connecting to SSH tunnel",
"status": "FAILED",
"message": "Auth fail"
}
],
"config": {
"public_key": "ssh-rsa ... fivetran user key",
"database": "database_name",
"password": "******",
"tunnel_port": "22",
"port": "5432",
"host": "test.host.com",
"tunnel_host": "test.tunnel.host.com",
"user": "user_name",
"connection_method": "SshTunnel",
"tunnel_user": "tunnel_user_name"
}
}
}
NOTE: You can use the new destination configuration response format for the following destinations:
Delete a destinationlink
Deletes a destination from your Fivetran account.
NOTE: Prior to performing this action, you need to remove all linked integrations with the destination by using either the Delete a connector API endpoint or your Fivetran dashboard.
Requestlink
DELETE https://api.fivetran.com/v1/destinations/{destination_id}
Path parameterslink
Name | Description |
---|---|
destination_id (required) | The unique identifier for the destination within your Fivetran account. |
Responselink
HTTP 200 OK
{
"code": "Success",
"message": "Destination with id 'destination_id' has been deleted"
}
V2 destination configuration response formatlink
We have implemented the new v2 format for consistency in the destination configuration information. This format is only valid for the following destinations:
To retrieve the destination configuration in the v2 format, you should add version=2
to the Accept
request header:
--header 'Accept: application/json;version=2'
In the new V2 format, the connection_method
field is renamed to connection_type
.
V1 response format:link
{
...
"config": {
...
"connection_method": "SshTunnel"
},
...
}
V2 response format:link
{
...
"config": {
...
"connection_type": "SshTunnel"
},
...
}