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'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 group management actions:
- Create a group
- List all groups
- Retrieve group details
- Retrieve group public SSH key
- Retrieve group service account
- Modify a group
- List all connectors within a group
- List all users within a group
- Add a user to a group
- Remove a user from a group
- Delete a group
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"
}