---
title: "Create a team hierarchy link"
method: POST
path: "/api/v2/team-hierarchy-links"
tags: ["Teams"]
---

# Create a team hierarchy link

`POST /api/v2/team-hierarchy-links`

Create a new team hierarchy link between a parent team and a sub team.

## Request body

- TeamHierarchyLinkCreateRequest — Request to create a team hierarchy link
  - `data` TeamHierarchyLinkCreate, required — Data provided when creating a team hierarchy link
    - `relationships` TeamHierarchyLinkCreateRelationships, required — The related teams that will be connected by the team hierarchy link
      - `parent_team` TeamHierarchyLinkCreateTeamRelationship, required — Data about each team that will be connected by the team hierarchy link
        - `data` TeamHierarchyLinkCreateTeam, required — This schema defines the attributes about each team that has to be provided when creating a team hierarchy link
          - `id` string, required — The team's identifier
          - `type` 'team', required — Team type
      - `sub_team` TeamHierarchyLinkCreateTeamRelationship, required — Data about each team that will be connected by the team hierarchy link
        - `data` TeamHierarchyLinkCreateTeam, required — This schema defines the attributes about each team that has to be provided when creating a team hierarchy link
          - `id` string, required — The team's identifier
          - `type` 'team', required — Team type
    - `type` 'team_hierarchy_links', required — Team hierarchy link type

## Response `200`

OK

- TeamHierarchyLinkResponse — Team hierarchy link response
  - `data` TeamHierarchyLink — Team hierarchy link
    - `attributes` TeamHierarchyLinkAttributes, required — Team hierarchy link attributes
      - `created_at` string, date-time, required — Timestamp when the team hierarchy link was created
      - `provisioned_by` string, required — The provisioner of the team hierarchy link
    - `id` string, required — The team hierarchy link's identifier
    - `relationships` TeamHierarchyLinkRelationships — Team hierarchy link relationships
      - `parent_team` TeamHierarchyLinkTeamRelationship, required — Team hierarchy link team relationship
        - `data` TeamHierarchyLinkTeam, required — Team hierarchy links connect different teams. This represents team objects that are connected by the team hierarchy link.
          - `attributes` TeamHierarchyLinkTeamAttributes — Team hierarchy links connect different teams. This represents attributes from teams that are connected by the team hierarchy link.
            - `avatar` string, nullable — The team's avatar
            - `banner` integer — The team's banner
            - `handle` string, required — The team's handle
            - `is_managed` boolean — Whether the team is managed
            - `is_open_membership` boolean — Whether the team has open membership
            - `link_count` integer — The number of links for the team
            - `name` string, required — The team's name
            - `summary` string, nullable — The team's summary
            - `user_count` integer — The number of users in the team
          - `id` string, required — The team's identifier
          - `type` 'team', required — Team type
      - `sub_team` TeamHierarchyLinkTeamRelationship, required — Team hierarchy link team relationship
        - `data` TeamHierarchyLinkTeam, required — Team hierarchy links connect different teams. This represents team objects that are connected by the team hierarchy link.
          - `attributes` TeamHierarchyLinkTeamAttributes — Team hierarchy links connect different teams. This represents attributes from teams that are connected by the team hierarchy link.
            - `avatar` string, nullable — The team's avatar
            - `banner` integer — The team's banner
            - `handle` string, required — The team's handle
            - `is_managed` boolean — Whether the team is managed
            - `is_open_membership` boolean — Whether the team has open membership
            - `link_count` integer — The number of links for the team
            - `name` string, required — The team's name
            - `summary` string, nullable — The team's summary
            - `user_count` integer — The number of users in the team
          - `id` string, required — The team's identifier
          - `type` 'team', required — Team type
    - `type` 'team_hierarchy_links', required — Team hierarchy link type
  - `included` TeamHierarchyLinkTeam[] — Included teams
    - `attributes` TeamHierarchyLinkTeamAttributes — Team hierarchy links connect different teams. This represents attributes from teams that are connected by the team hierarchy link.
      - `avatar` string, nullable — The team's avatar
      - `banner` integer — The team's banner
      - `handle` string, required — The team's handle
      - `is_managed` boolean — Whether the team is managed
      - `is_open_membership` boolean — Whether the team has open membership
      - `link_count` integer — The number of links for the team
      - `name` string, required — The team's name
      - `summary` string, nullable — The team's summary
      - `user_count` integer — The number of users in the team
    - `id` string, required — The team's identifier
    - `type` 'team', required — Team type
  - `links` TeamsHierarchyLinksResponseLinks — When querying team hierarchy links, a set of links for navigation between different pages is included
    - `first` string, nullable — Link to the first page.
    - `last` string, nullable — Link to the last page.
    - `next` string, nullable — Link to the next page.
    - `prev` string, nullable — Link to the previous page.
    - `self` string — Link to the current object.

## Other responses

- `403` — Forbidden
- `409` — Conflict
- `429` — Too many requests

---

[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)