---
title: "Link Teams with GitHub Teams"
method: POST
path: "/api/v2/team/sync"
tags: ["Teams"]
---

# Link Teams with GitHub Teams

`POST /api/v2/team/sync`

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/),
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`.

## Request body

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

## Response `200`

OK

## Other responses

- `204` — No Content
- `403` — Forbidden
- `429` — Too many requests
- `500` — Internal Server Error - Unexpected error during linking.

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/versions/da68bf029e4c/schema)