For AI agents: A markdown version of this page is available at https://dnd37xeb23o8n.cloudfront.net/jen.gilbert/astro-base/api/latest/teams/link-teams-with-external-teams.md. A documentation index is available at /llms.txt.
homeHomedocsDocsapiAPI
Language
Datadog site

Link teams with external teams

POSThttps://api.datadoghq.com/api/v2/team/synchttps://api.us3.datadoghq.com/api/v2/team/synchttps://api.us5.datadoghq.com/api/v2/team/synchttps://api.datadoghq.eu/api/v2/team/synchttps://api.ap1.datadoghq.com/api/v2/team/synchttps://api.ap2.datadoghq.com/api/v2/team/synchttps://api.uk1.datadoghq.com/api/v2/team/synchttps://api.ddog-gov.com/api/v2/team/synchttps://api.us2.ddog-gov.com/api/v2/team/sync

Overview

This endpoint configures synchronization between your existing Datadog teams and teams from GitHub or ServiceNow by matching team names. It evaluates all current Datadog teams and compares them against teams in the external source connected to your Datadog account.

This operation is read-only on the external source side, no teams will be modified or created there. This only creates new teams in Datadog when type is set to provision.

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

GitHub: A GitHub organization must be connected to your Datadog account, 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 (lowercased and kebab-cased) using a normalized exact match; case is ignored and spaces are removed.

ServiceNow: The ServiceNow integration must be configured for your Datadog account. Active assignment groups from every configured ServiceNow instance are synchronized, and the ServiceNow group hierarchy is preserved. When sync_membership is enabled, group members are matched to Datadog users by email address.

This endpoint requires the teams_manage permission.

OAuth apps require the teams_manage authorization scope to access this endpoint.

Request

Body Data (required)

Field
Type
Description
data [required]
object

A configuration governing syncing between Datadog teams and teams from an external system.

Response

OK

Code Example

# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF
# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"

curl -X POST "https://api.${DD_SITE}/api/v2/team/sync" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
  "data": {
    "attributes": {
      "source": "github",
      "type": "link"
    },
    "type": "team_sync_bulk"
  }
}
EOF