---
title: Link Teams with GitHub Teams
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: Docs > API Reference > Teams
---

# Link Teams with GitHub Teams{% #link-teams-with-github-teams %}

{% tab title="v2" %}

| Datadog site      | API endpoint                                        |
| ----------------- | --------------------------------------------------- |
| ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/team/sync |
| ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/team/sync |
| app.datadoghq.eu  | POST https://api.datadoghq.eu/api/v2/team/sync      |
| app.ddog-gov.com  | POST https://api.ddog-gov.com/api/v2/team/sync      |
| us2.ddog-gov.com  | POST https://api.us2.ddog-gov.com/api/v2/team/sync  |
| app.datadoghq.com | POST https://api.datadoghq.com/api/v2/team/sync     |
| us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/team/sync |
| us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/team/sync |

### Overview



This endpoint configures synchronization between your existing Datadog teams and GitHub teams by matching their names. It evaluates all current Datadog teams and compares them against teams in the GitHub organization connected to your Datadog account, based on Datadog Team handle and GitHub Team slug (lowercased and kebab-cased).

This operation is read-only on the GitHub side, no teams will be modified or created.

Optionally, provide `selection_state` to limit synchronization to specific teams or organizations and their subtrees, instead of syncing all teams.

[A GitHub organization must be connected to your Datadog account](https://docs.datadoghq.com/integrations/github.md), and the GitHub App integrated with Datadog must have the `Members Read` permission. Matching is performed by comparing the Datadog team handle to the GitHub team slug using a normalized exact match; case is ignored and spaces are removed. No modifications are made to teams in GitHub. This only creates new teams in Datadog when type is set to `provision`.
This endpoint requires the `teams_manage` permission.
OAuth apps require the `teams_manage` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#teams) to access this endpoint.



### Request

#### Body Data (required)



{% tab title="Model" %}

| Parent field    | Field                         | Type     | Description                                                                                                                                                                          |
| --------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                 | data [*required*]        | object   | A configuration governing syncing between Datadog teams and teams from an external system.                                                                                           |
| data            | attributes [*required*]  | object   | Team sync attributes.                                                                                                                                                                |
| attributes      | frequency                     | enum     | How often the sync process should be run. Defaults to `once` when not provided. Allowed enum values: `once,continuously,paused`                                                      |
| attributes      | selection_state               | [object] | Specifies which teams or organizations to sync. When provided, synchronization is limited to the specified items and their subtrees.                                                 |
| selection_state | external_id [*required*] | object   | The external identifier for a team or organization in the source platform.                                                                                                           |
| external_id     | type [*required*]        | enum     | The type of external identifier for the selection state item. For GitHub synchronization, the allowed values are `team` and `organization`. Allowed enum values: `team,organization` |
| external_id     | value [*required*]       | string   | The external identifier value from the source platform. For GitHub, this is the string representation of a GitHub organization ID or team ID.                                        |
| selection_state | operation                     | enum     | The operation to perform on the selected hierarchy. When set to `include`, synchronization covers the referenced teams or organizations. Allowed enum values: `include`              |
| selection_state | scope                         | enum     | The scope of the selection. When set to `subtree`, synchronization includes the referenced team or organization and everything nested under it. Allowed enum values: `subtree`       |
| attributes      | source [*required*]      | enum     | The external source platform for team synchronization. Only "github" is supported. Allowed enum values: `github`                                                                     |
| attributes      | sync_membership               | boolean  | Whether to sync members from the external team to the Datadog team. Defaults to `false` when not provided.                                                                           |
| attributes      | type [*required*]        | enum     | The type of synchronization operation. "link" connects teams by matching names. "provision" creates new teams when no match is found. Allowed enum values: `link,provision`          |
| data            | id                            | string   | The sync's identifier                                                                                                                                                                |
| data            | type [*required*]        | enum     | Team sync bulk type. Allowed enum values: `team_sync_bulk`                                                                                                                           |

{% /tab %}

{% tab title="Example" %}

```json
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link",
      "selection_state": [
        {
          "external_id": {
            "type": "organization",
            "value": "1"
          }
        }
      ]
    },
    "type": "team_sync_bulk"
  }
}
```

{% /tab %}

### Response

{% tab title="200" %}
OK
{% /tab %}

{% tab title="204" %}
No Content
{% /tab %}

{% tab title="403" %}
Forbidden
{% tab title="Model" %}
API error response.

| Field                    | Type     | Description       |
| ------------------------ | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |

{% /tab %}

{% tab title="Example" %}

```json
{
  "errors": [
    "Bad Request"
  ]
}
```

{% /tab %}

{% /tab %}

{% tab title="429" %}
Too many requests
{% tab title="Model" %}
API error response.

| Field                    | Type     | Description       |
| ------------------------ | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |

{% /tab %}

{% tab title="Example" %}

```json
{
  "errors": [
    "Bad Request"
  ]
}
```

{% /tab %}

{% /tab %}

{% tab title="500" %}
Internal Server Error - Unexpected error during linking.
{% tab title="Model" %}
API error response.

| Field                    | Type     | Description       |
| ------------------------ | -------- | ----------------- |
| errors [*required*] | [string] | A list of errors. |

{% /tab %}

{% tab title="Example" %}

```json
{
  "errors": [
    "Bad Request"
  ]
}
```

{% /tab %}

{% /tab %}

### Code Example

##### 
                          \## default
# 
 \# Curl command curl -X POST "https://api.datadoghq.com/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "DD-API-KEY: ${DD_API_KEY}" \
-H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF 
                        
##### 

```go
// Link Teams with GitHub Teams returns "OK" response

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/DataDog/datadog-api-client-go/v2/api/datadog"
	"github.com/DataDog/datadog-api-client-go/v2/api/datadogV2"
)

func main() {
	body := datadogV2.TeamSyncRequest{
		Data: datadogV2.TeamSyncData{
			Attributes: datadogV2.TeamSyncAttributes{
				Source: datadogV2.TEAMSYNCATTRIBUTESSOURCE_GITHUB,
				Type:   datadogV2.TEAMSYNCATTRIBUTESTYPE_LINK,
			},
			Type: datadogV2.TEAMSYNCBULKTYPE_TEAM_SYNC_BULK,
		},
	}
	ctx := datadog.NewDefaultContext(context.Background())
	configuration := datadog.NewConfiguration()
	apiClient := datadog.NewAPIClient(configuration)
	api := datadogV2.NewTeamsApi(apiClient)
	r, err := api.SyncTeams(ctx, body)

	if err != nil {
		fmt.Fprintf(os.Stderr, "Error when calling `TeamsApi.SyncTeams`: %v\n", err)
		fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r)
	}
}
```

#### Instructions

First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=go) and then save the example to `main.go` and run following commands:
    DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" go run "main.go"
##### 

```java
// Link Teams with GitHub Teams returns "OK" response

import com.datadog.api.client.ApiClient;
import com.datadog.api.client.ApiException;
import com.datadog.api.client.v2.api.TeamsApi;
import com.datadog.api.client.v2.model.TeamSyncAttributes;
import com.datadog.api.client.v2.model.TeamSyncAttributesSource;
import com.datadog.api.client.v2.model.TeamSyncAttributesType;
import com.datadog.api.client.v2.model.TeamSyncBulkType;
import com.datadog.api.client.v2.model.TeamSyncData;
import com.datadog.api.client.v2.model.TeamSyncRequest;

public class Example {
  public static void main(String[] args) {
    ApiClient defaultClient = ApiClient.getDefaultApiClient();
    TeamsApi apiInstance = new TeamsApi(defaultClient);

    TeamSyncRequest body =
        new TeamSyncRequest()
            .data(
                new TeamSyncData()
                    .attributes(
                        new TeamSyncAttributes()
                            .source(TeamSyncAttributesSource.GITHUB)
                            .type(TeamSyncAttributesType.LINK))
                    .type(TeamSyncBulkType.TEAM_SYNC_BULK));

    try {
      apiInstance.syncTeams(body);
    } catch (ApiException e) {
      System.err.println("Exception when calling TeamsApi#syncTeams");
      System.err.println("Status code: " + e.getCode());
      System.err.println("Reason: " + e.getResponseBody());
      System.err.println("Response headers: " + e.getResponseHeaders());
      e.printStackTrace();
    }
  }
}
```

#### Instructions

First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=java) and then save the example to `Example.java` and run following commands:
    DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" java "Example.java"
##### 

```python
"""
Link Teams with GitHub Teams returns "OK" response
"""

from datadog_api_client import ApiClient, Configuration
from datadog_api_client.v2.api.teams_api import TeamsApi
from datadog_api_client.v2.model.team_sync_attributes import TeamSyncAttributes
from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
from datadog_api_client.v2.model.team_sync_attributes_type import TeamSyncAttributesType
from datadog_api_client.v2.model.team_sync_bulk_type import TeamSyncBulkType
from datadog_api_client.v2.model.team_sync_data import TeamSyncData
from datadog_api_client.v2.model.team_sync_request import TeamSyncRequest

body = TeamSyncRequest(
    data=TeamSyncData(
        attributes=TeamSyncAttributes(
            source=TeamSyncAttributesSource.GITHUB,
            type=TeamSyncAttributesType.LINK,
        ),
        type=TeamSyncBulkType.TEAM_SYNC_BULK,
    ),
)

configuration = Configuration()
with ApiClient(configuration) as api_client:
    api_instance = TeamsApi(api_client)
    api_instance.sync_teams(body=body)
```

#### Instructions

First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=python) and then save the example to `example.py` and run following commands:
    DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" python3 "example.py"
##### 

```ruby
# Link Teams with GitHub Teams returns "OK" response

require "datadog_api_client"
api_instance = DatadogAPIClient::V2::TeamsAPI.new

body = DatadogAPIClient::V2::TeamSyncRequest.new({
  data: DatadogAPIClient::V2::TeamSyncData.new({
    attributes: DatadogAPIClient::V2::TeamSyncAttributes.new({
      source: DatadogAPIClient::V2::TeamSyncAttributesSource::GITHUB,
      type: DatadogAPIClient::V2::TeamSyncAttributesType::LINK,
    }),
    type: DatadogAPIClient::V2::TeamSyncBulkType::TEAM_SYNC_BULK,
  }),
})
p api_instance.sync_teams(body)
```

#### Instructions

First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=ruby) and then save the example to `example.rb` and run following commands:
    DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" rb "example.rb"
##### 

```rust
// Link Teams with GitHub Teams returns "OK" response
use datadog_api_client::datadog;
use datadog_api_client::datadogV2::api_teams::TeamsAPI;
use datadog_api_client::datadogV2::model::TeamSyncAttributes;
use datadog_api_client::datadogV2::model::TeamSyncAttributesSource;
use datadog_api_client::datadogV2::model::TeamSyncAttributesType;
use datadog_api_client::datadogV2::model::TeamSyncBulkType;
use datadog_api_client::datadogV2::model::TeamSyncData;
use datadog_api_client::datadogV2::model::TeamSyncRequest;

#[tokio::main]
async fn main() {
    let body = TeamSyncRequest::new(TeamSyncData::new(
        TeamSyncAttributes::new(
            TeamSyncAttributesSource::GITHUB,
            TeamSyncAttributesType::LINK,
        ),
        TeamSyncBulkType::TEAM_SYNC_BULK,
    ));
    let configuration = datadog::Configuration::new();
    let api = TeamsAPI::with_config(configuration);
    let resp = api.sync_teams(body).await;
    if let Ok(value) = resp {
        println!("{:#?}", value);
    } else {
        println!("{:#?}", resp.unwrap_err());
    }
}
```

#### Instructions

First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=rust) and then save the example to `src/main.rs` and run following commands:
    DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" cargo run
##### 

```typescript
/**
 * Link Teams with GitHub Teams returns "OK" response
 */

import { client, v2 } from "@datadog/datadog-api-client";

const configuration = client.createConfiguration();
const apiInstance = new v2.TeamsApi(configuration);

const params: v2.TeamsApiSyncTeamsRequest = {
  body: {
    data: {
      attributes: {
        source: "github",
        type: "link",
      },
      type: "team_sync_bulk",
    },
  },
};

apiInstance
  .syncTeams(params)
  .then((data: any) => {
    console.log(
      "API called successfully. Returned data: " + JSON.stringify(data)
    );
  })
  .catch((error: any) => console.error(error));
```

#### Instructions

First [install the library and its dependencies](https://docs.datadoghq.com/api/latest.md?code-lang=typescript) and then save the example to `example.ts` and run following commands:
    DD_SITE="datadoghq.com" DD_API_KEY="<DD_API_KEY>" DD_APP_KEY="<DD_APP_KEY>" tsc "example.ts"
{% /tab %}