> ## Documentation Index
> Fetch the complete documentation index at: https://developers.pleo.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Team

> Use this endpoint to create a new team for the company or organisation the access token is scoped to. If organizationId is supplied, it takes precedence and the access token must be scoped to that organisation. Otherwise, companyId is used if supplied (the access token must have access to that company), defaulting to the company the access token is scoped to if neither is supplied. Team names must be unique (case-insensitive) within the company and its organisation.



## OpenAPI

````yaml post /v1/teams
openapi: 3.0.1
info:
  title: Oberon API
  description: Oberon open api definitions
  termsOfService: https://pleo.io/terms/
  contact:
    email: apiteam@pleo.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 52.35.0
servers:
  - url: https://external.pleo.io
    description: Production server
  - url: https://external.staging.pleo.io
    description: Staging server
security:
  - bearerAuth: []
  - basicAuth: []
tags:
  - name: SCIM
    description: >-
      SCIM-compatible User API. The SCIM (System for Cross-domain Identity

      Management) specification standardises a schema for user representation
      and

      provides a RESTful API to create, update, retrieve and delete user
      identities.

      <br> In particular, this API enables third-party systems to efficiently
      manage

      user provisioning and de-provisioning.
       <br> API available at `/scim/v2`
    externalDocs:
      description: Read more about SCIM
      url: https://datatracker.ietf.org/doc/html/rfc7644
  - name: Employees
    description: |-
      The Employees API enables you to search for employee records that
      are managed in Pleo. You can perform the following: 
       - Search for multiple
      employees 
       - Search for a specific employee record by employee ID
  - name: Companies
    description: >-
      The Companies API enables you to search for company records that are
      managed in Pleo. You can perform the following: 
       - Search for multiple companies
       - Search for a specific company record by company ID
  - name: Teams
    description: >-
      The Teams API enables you to manage teams within a company or organisation
      that are managed in Pleo. You can perform the following: 
       - Search for teams
       - Get a team by ID
       - Create a team
       - Partially update a team
       - Delete a team
       - Add members to a team
       - Remove a member from a team
paths:
  /v1/teams:
    post:
      tags:
        - Teams
      summary: Create a Team
      description: >-
        Use this endpoint to create a new team for the company or organisation
        the access token is scoped to. If organizationId is supplied, it takes
        precedence and the access token must be scoped to that organisation.
        Otherwise, companyId is used if supplied (the access token must have
        access to that company), defaulting to the company the access token is
        scoped to if neither is supplied. Team names must be unique
        (case-insensitive) within the company and its organisation.
      operationId: Create Team
      requestBody:
        content:
          application/json;charset=UTF-8:
            schema:
              $ref: '#/components/schemas/ExternalTeamCreateRequest'
      responses:
        '201':
          description: Team resource created
          content:
            application/json;charset=UTF-8:
              schema:
                $ref: '#/components/schemas/DataResponseExternalTeamResponseModel'
        '400':
          description: >-
            Bad request: Invalid team name, or a team with that name already
            exists
        '403':
          description: 'Forbidden: User lacks the necessary permissions'
components:
  schemas:
    ExternalTeamCreateRequest:
      required:
        - name
      type: object
      properties:
        code:
          type: string
          description: External ID of the Team
        companyId:
          type: string
          description: >-
            ID of the Company to create the Team under. Defaults to the company
            the access token is scoped to if omitted. Ignored if organizationId
            is provided.
          format: uuid
        name:
          type: string
          description: Name of the Team
        organizationId:
          type: string
          description: >-
            ID of the Organisation to create the Team under. The access token
            must be scoped to this organisation. Takes precedence over companyId
            if both are provided.
          format: uuid
    DataResponseExternalTeamResponseModel:
      required:
        - data
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ExternalTeamResponseModel'
    ExternalTeamResponseModel:
      required:
        - createdAt
        - id
        - name
        - updatedAt
      type: object
      properties:
        code:
          type: string
          description: External ID of the Team
        companyId:
          type: string
          description: Company ID of the Team
          format: uuid
        createdAt:
          type: string
          description: Creation date of the Team
          format: date-time
        employees:
          type: array
          description: Employee IDs of the Team's employees
          items:
            type: string
            description: Employee IDs of the Team's employees
            format: uuid
        id:
          type: string
          description: ID of the Team
          format: uuid
        name:
          type: string
          description: Name of the Team
        organizationId:
          type: string
          description: Organisation ID of the Team
          format: uuid
        updatedAt:
          type: string
          description: Last update date of the Team
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      description: >-
        JWT Bearer token authentication. Include the token in the Authorization
        header as: `Bearer <token>`
      scheme: bearer
      bearerFormat: JWT
    basicAuth:
      type: http
      description: >-
        Basic HTTP authentication using API key. Use your API key as the
        username and leave the password empty. The credentials will be Base64
        encoded automatically.
      scheme: basic

````