Group Management

IMPORTANT: Groups and destinations 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's group_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 same group_id value, which is unique in your Fivetran account. The group's name corresponds to the Destination name you specify in your Fivetran dashboard when creating the destination in your Fivetran dashboard.

REST API supports the following group management actions:

Create a Group

Creates a new group in your Fivetran account.

Request

POST https://api.fivetran.com/v1/groups

{
    "name": "Primary_Snowflake"
}

Payload parameters

Name	Description
`name` (required)	The group name within the account. The name must start with a letter or underscore and can only contain letters, numbers, or underscores.

Response

HTTP 201 CREATED

{
    "code": "Success",
    "message": "Group has been created",
    "data": {
        "id": "decent_dropsy",
        "name": "Primary_Snowflake",
        "created_at": "2020-05-25T15:26:47.306509Z"
    }
}

List All Groups

Returns a list of all groups within your Fivetran account.

Request

GET https://api.fivetran.com/v1/groups

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 1..1000, the default value is 100

Response

HTTP 200 OK

{
    "code": "Success",
    "data": {
        "items": [
            {
                "id": "projected_sickle",
                "name": "Staging",
                "created_at": "2018-12-20T11:59:35.089589Z"
            },
            {
                "id": "schoolmaster_heedless",
                "name": "Production",
                "created_at": "2019-01-08T19:53:52.185146Z"
            }
        ],
        "next_cursor": "eyJza2lwIjoyfQ"
    }
}

Fields

Name	Description
`items`	The collection of groups
`next_cursor`	The value of the `cursor` parameter for the next page

Retrieve Group Details

Returns a group object if a valid identifier was provided.

Request

GET https://api.fivetran.com/v1/groups/{group_id}

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

Response

HTTP 200 OK

{
    "code": "Success",
    "data": {
        "id": "projected_sickle",
        "name": "Staging",
        "created_at": "2018-12-20T11:59:35.089589Z"
    }
}

Fields

Name	Description
`id`	The unique identifier for the group within the Fivetran system.
`name`	The name of the group within your account.
`created_at`	The timestamp of when the group was created in your account.

Retrieve Group Public SSH Key

Returns a group public SSH key if a valid group identifier was provided.

Request

GET https://api.fivetran.com/v1/groups/{group_id}/public-key

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

Response

HTTP 200 OK

{
    "code": "Success",
    "data": {
        "public_key": "raw_ssh_public_key_value"
    }
}

Fields

Name	Description
`public_key`	Public key from SSH key pair associated with the group.

Retrieve Group Service Account

Returns a group service account if a valid group identifier was provided.

Request

GET https://api.fivetran.com/v1/groups/{group_id}/service-account

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

Response

HTTP 200 OK

{
    "code": "Success",
    "data": {
        "service_account": "service_account"
    }
}

Fields

Name	Description
`service_account`	Fivetran service account associated with the group.

Modify a Group

Updates information for an existing group within your Fivetran account.

Request

PATCH https://api.fivetran.com/v1/groups/{group_id}

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

{
    "name": "New_Group_Name"
}

Payload parameters

Name	Description
`name` (required)	The group name within the account. The name must start with a letter or underscore and can only contain letters, numbers, or underscores.

Response

HTTP 200 OK

{
    "code": "Success",
    "message": "Group has been updated",
    "data": {
        "id": "decent_dropsy",
        "name": "New_Group_Name",
        "created_at": "2020-05-25T15:26:47.306509Z"
    }
}

List All Connectors within a Group

Returns a list of information about all connectors within a group in your Fivetran account.

Request

GET https://api.fivetran.com/v1/groups/{group_id}/connectors

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

Query parameters

Name	Description
`schema`	optional filter. When used, the response will only contain information for the connector with the specified schema
`cursor`	paging cursor, read more about pagination
`limit`	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": "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"
    }
}

Fields

Name	Description
`items`	The collection of group connectors
`next_cursor`	The value of the `cursor` parameter for the next page

List All Users within a Group

Returns a list of information about all users within a group in your Fivetran account.

Request

GET https://api.fivetran.com/v1/groups/{group_id}/users

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

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 1..1000, the default value is 100

Response

HTTP 200 OK

{
    "code": "Success",
    "data": {
        "items": [
            {
                "id": "nozzle_eat",
                "email": "john@mycompany.com",
                "given_name": "John",
                "family_name": "White",
                "verified": true,
                "invited": false,
                "picture": null,
                "phone": null,
                "role": null,
                "logged_in_at": "2019-01-03T08:44:45.369Z",
                "created_at": "2018-01-15T11:00:27.329220Z",
                "active": true
            }
        ],
        "next_cursor": "eyJza2lwIjoxfQ"
    }
}

Fields

Name	Description
`items`	The collection of group users
`next_cursor`	The value of the `cursor` parameter for the next page

Add a User to a Group

Adds an existing user to a group in your Fivetran account.

Request

POST https://api.fivetran.com/v1/groups/{group_id}/users

{
    "email": "john.white@mycompany.com",
    "role": "Account Administrator"
}

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.

Payload parameters

Name	Description
`email` (required)	The email address that the user has associated with their user profile.
`role` (required)	The group role that you would like to assign this new user to. Supported group roles: `Destination Administrator`, `Destination Reviewer`, `Destination Analyst`, `Connector Creator`, or a custom destination role.

Response

HTTP 200 OK

{
    "code": "Success",
    "message": "User has been added to the group"
}

Remove a User from a Group

Removes an existing user from a group in your Fivetran account.

Request

DELETE https://api.fivetran.com/v1/groups/{group_id}/users/{user_id}

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within the Fivetran system.
`user_id` (required)	The unique identifier for the user within the Fivetran system.

Response

HTTP 200 OK

{
    "code": "Success",
    "message": "User with id 'nozzle_eat' has been removed from the group"
}

Delete a group

Deletes a group from your Fivetran account.

NOTE: Prior to performing this action, you need to remove the destination linked to the group by using the Delete a destination API endpoint.

Request

DELETE https://api.fivetran.com/v1/groups/{group_id}

Path parameters

Name	Description
`group_id` (required)	The unique identifier for the group within your Fivetran account.

Response

HTTP 200 OK

{
    "code": "Success",
    "message": "Group with id 'group_id' has been deleted"
}