openapi: 3.0.0
info:
  version: 1.0.0
  title: Channel Accounts Teammate groups API
  contact:
    name: Front Platform
    url: https://community.front.com
servers:
- url: https://api2.frontapp.com
security:
- http: []
tags:
- name: Teammate groups
paths:
  /teammate_groups:
    get:
      summary: List teammate groups
      operationId: list-company-teammate-groups
      description: 'List the teammate groups in the company.


        Required scope: `teammate_groups:read`'
      tags:
      - Teammate groups
      responses:
        '200':
          $ref: '#/components/responses/listOfTeammateGroups'
      x-required-scopes:
      - teammate_groups:read
    post:
      summary: Create teammate group
      operationId: create-company-teammate-group
      description: 'Create a new teammate group.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeammateGroup'
      responses:
        '201':
          $ref: '#/components/responses/teammateGroup'
      x-required-scopes:
      - teammate_groups:write
  /teammate_groups/{teammate_group_id}:
    get:
      summary: Get teammate group
      operationId: get-company-teammate-group
      description: 'Fetch a teammate group.


        Required scope: `teammate_groups:read`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      responses:
        '200':
          $ref: '#/components/responses/teammateGroup'
      x-required-scopes:
      - teammate_groups:read
    patch:
      summary: Update a teammate group
      operationId: update-a-company-teammate-group
      description: 'Updates a teammate group. Note - You cannot modify a teammate group that is managed by SCIM.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTeammateGroup'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
    delete:
      summary: Delete teammate group
      operationId: delete-company-teammate-group
      description: 'Deletes a teammate group. Note - You cannot delete a teammate group that is managed by SCIM.


        Required scope: `teammate_groups:delete`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:delete
  /teammate_groups/{teammate_group_id}/inboxes:
    get:
      summary: List teammate group team inboxes
      operationId: list-company-teammate-group-team-inboxes
      description: 'List inboxes that the teammate group has access to via its associated teams.


        Required scope: `inboxes:read`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      responses:
        '200':
          $ref: '#/components/responses/listOfInboxes'
      x-required-scopes:
      - inboxes:read
    post:
      summary: Add teammate group team inboxes
      operationId: add-company-teammate-group-team-inboxes
      description: 'Links non-public inboxes to the teammate group. The inbox must be part of a team that has been added to the teammate group.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        description: Inbox IDs to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxIds'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
    delete:
      summary: Remove teammate group team inboxes
      operationId: remove-company-teammate-group-team-inboxes
      description: 'Unlinks non-public inboxes from the teammate group.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        description: Inbox IDs to remove
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InboxIds'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
  /teammate_groups/{teammate_group_id}/teammates:
    get:
      summary: List teammate group teammates
      operationId: list-company-teammate-group-teammates
      description: 'List teammate group teammates.


        Required scope: `teammates:read`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      responses:
        '200':
          $ref: '#/components/responses/listOfTeammates'
      x-required-scopes:
      - teammates:read
    post:
      summary: Add teammate group teammates
      operationId: add-company-teammate-group-teammates
      description: 'Add teammate group teammates. Note - You cannot modify a teammate group that is managed by SCIM.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        description: Teammate IDs to add. Alternatively, you can supply emails as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeammateIds'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
    delete:
      summary: Remove teammate group teammates
      operationId: remove-company-teammate-group-teammates
      description: 'Remove teammate group teammates. Note - You cannot modify a teammate group that is managed by SCIM.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        description: Teammate IDs to remove. Alternatively, you can supply emails as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeammateIds'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
  /teammate_groups/{teammate_group_id}/teams:
    get:
      summary: List teammate group teams
      operationId: list-company-teammate-group-teams
      description: 'List teams added to the teammate group. Any teams added to the teammate group will automatically link public inboxes.


        Required scope: `teams:read`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      responses:
        '200':
          $ref: '#/components/responses/listOfTeams'
      x-required-scopes:
      - teams:read
    post:
      summary: Add teammate group teams
      operationId: add-company-teammate-group-teams
      description: 'Adds teams to the teammate group. Any teams added to the teammate group will automatically link public inboxes. Non-public inboxes can be added to the teammate group separately.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        description: Team IDs to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamIds'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
    delete:
      summary: Remove teammate group teams
      operationId: remove-company-teammate-group-teams
      description: 'Remove teams from the teammate group. Unlinks to any associated team inboxes.


        Required scope: `teammate_groups:write`'
      tags:
      - Teammate groups
      parameters:
      - in: path
        name: teammate_group_id
        required: true
        description: The teammate group ID.
        schema:
          type: string
          default: cir_123
      requestBody:
        description: Team IDs to remove.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TeamIds'
      responses:
        '204':
          description: No content
      x-required-scopes:
      - teammate_groups:write
components:
  schemas:
    TeamIds:
      type: object
      required:
      - team_ids
      properties:
        team_ids:
          type: array
          items:
            $ref: '#/components/schemas/ResourceID'
    TeammateIds:
      type: object
      required:
      - teammate_ids
      properties:
        teammate_ids:
          type: array
          items:
            $ref: '#/components/schemas/ResourceID'
    InboxResponse:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6
            related:
              type: object
              properties:
                teammates:
                  type: string
                  description: Link to inbox teammates
                  example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6/teammates
                conversations:
                  type: string
                  description: Link to inbox conversations
                  example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6/conversations
                channels:
                  type: string
                  description: Link to inbox channels
                  example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6/channels
                owner:
                  type: string
                  description: Link to inbox owner
                  example: https://yourCompany.api.frontapp.com/teams/tim_k30
        id:
          type: string
          description: Unique identifier for the inbox
          example: inb_1ix6
        name:
          type: string
          description: Name of the inbox
          example: The Dundies
        is_private:
          type: boolean
          description: Whether or not the inbox is individual
          example: false
        is_public:
          type: boolean
          description: Whether or not the inbox is available to all members of a team by default
          example: true
        custom_fields:
          description: Custom fields for this inbox
          $ref: '#/components/schemas/CustomFieldParameter'
    InboxIds:
      type: object
      required:
      - inbox_ids
      properties:
        inbox_ids:
          type: array
          items:
            $ref: '#/components/schemas/ResourceID'
    UpdateTeammateGroup:
      type: object
      properties:
        name:
          type: string
          description: Name of the teammate group
        description:
          type: string
          description: Description of the teammate group
        permissions:
          type: object
          description: Permissions for the teammate group
          properties:
            contacts:
              type: object
              description: Permissions for accessing contact lists. This only applies if shared contacts permissions are enabled.
              required:
              - access
              properties:
                access:
                  type: string
                  description: One of 'all', 'contact_groups', 'contact_lists', or 'none'.
                contact_group_ids:
                  type: array
                  deprecated: true
                  description: List of contact group ids. Can only be specified if access is set to 'contact_groups'. ⚠️ Deprecated. Use access 'contact_lists' and 'contact_list_ids' instead.
                  items:
                    type: string
                contact_list_ids:
                  type: array
                  description: List of contact list ids. Can only be specified if access is set to 'contact_lists'.
                  items:
                    type: string
    CustomFieldParameter:
      type: object
      description: An object whose key is the `name` property defined for the custom field in the Front UI. The value of the key must use the same `type` specified for the custom field, as described in https://dev.frontapp.com/reference/custom-fields
      example:
        city: London, UK
        isVIP: true
        renewal_date: 1525417200
        sla_time: 90
        owner: leela@planet-express.com
        replyTo: inb_55c8c149
        Job Title: firefighter
    ResourceID:
      type: string
    CreateTeammateGroup:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          description: Name of the teammate group
        description:
          type: string
          description: Description of the teammate group
        permissions:
          type: object
          description: Permissions for the teammate group
          properties:
            contacts:
              type: object
              description: Permissions for accessing contact lists. This only applies if shared contacts permissions are enabled.
              required:
              - access
              properties:
                access:
                  type: string
                  description: One of 'all', 'contact_groups', 'contact_lists', or 'none'.
                contact_group_ids:
                  type: array
                  deprecated: true
                  description: List of contact group ids. Can only be specified if access is set to 'contact_groups'. ⚠️ Deprecated. Use access 'contact_lists' and 'contact_list_ids' instead.
                  items:
                    type: string
                contact_list_ids:
                  type: array
                  description: List of contact list ids. Can only be specified if access is set to 'contact_lists'.
                  items:
                    type: string
    TeammateGroupResponse:
      type: object
      description: A teammate group is a group of teammates in Front.
      required:
      - _links
      - id
      - name
      - description
      - is_managed_by_scim
      - permissions
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/teammate_groups/cir_123
            related:
              type: object
              properties:
                teammates:
                  type: string
                  description: Link to list of teammate members
                  example: https://yourCompany.api.frontapp.com/teammate_groups/cir_123/teammates
                teams:
                  type: string
                  description: Link to list of associated teams
                  example: https://yourCompany.api.frontapp.com/teammate_groups/cir_123/teams
                inboxes:
                  type: string
                  description: Link to list of inboxes that teammate members can access
                  example: https://yourCompany.api.frontapp.com/teammate_groups/cir_123/inboxes
        id:
          type: string
          description: Unique identifier of the teammate group
          example: cir_123
        name:
          type: string
          description: The name of the teammate group
          example: Sales team
        description:
          type: string
          nullable: true
          description: Description of the teammate group
          example: Best sales team ever
        is_managed_by_scim:
          type: boolean
          description: Is teammate group managed by SCIM or by Front
          example: false
        permissions:
          type: object
          description: Permissions for the teammate group
          example:
            contacts:
              access: contact_lists
              contact_list_ids:
              - grp_1
              - grp_2
          properties:
            contacts:
              type: object
              description: Permissions for teammate group access to contact lists
              properties:
                access:
                  type: string
                  description: Level of access for the teammate group to contact lists. Must be one of 'all', 'contact_lists', or 'none'.
                contact_list_ids:
                  type: array
                  description: List of contact lists the teammate group is allowed to access. May only be specified if 'access' is set to 'contact_lists'.
                  example:
                  - grp_123
                  - grp_456
                  items:
                    type: string
    TeammateResponse:
      type: object
      description: A teammate is a user in Front.
      required:
      - _links
      - id
      - email
      - username
      - first_name
      - last_name
      - license_type
      - is_admin
      - is_available
      - is_blocked
      - type
      - custom_fields
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a
            related:
              type: object
              properties:
                inboxes:
                  type: string
                  description: Link to teammate's inboxes
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a/inboxes
                conversations:
                  type: string
                  description: Link to teammate's conversations
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a/conversations
                botSource:
                  type: string
                  description: Link to the source resource of the bot (e.g. rule)
                  example: https://yourCompany.api.frontapp.com/rules/rul_6r55a
        id:
          type: string
          description: Unique identifier of the teammate
          example: tea_6r55a
        email:
          type: string
          description: Email address of the teammate
          example: michael.scott@dundermifflin.com
        username:
          type: string
          description: Username of the teammate (used for "@" mentions)
          example: PrisonMike
        first_name:
          type: string
          description: First name of the teammate
          example: Michael
        last_name:
          type: string
          description: Last name of the teammate
          example: Scott
        is_admin:
          type: boolean
          description: Whether or not the teammate is an admin in your company
          example: true
        is_available:
          type: boolean
          description: Whether or not the teammate is available
          example: false
        is_blocked:
          type: boolean
          description: Whether or not the teammate account has been blocked
          example: false
        type:
          type: string
          description: "Type of the teammate, normal teammates are denoted as \"user\", while visitors are denoted as \"visitor\".\nBot users are denoted by their parent resource type.\nThe following bot types are available:\n  * rule: acting on behalf of a Rule, author of comments and drafts\n  * macro: acting on behalf of a Macro, author of comments and drafts\n  * API: acting on behalf of OAuth clients\n  * integration: acting on behalf of an Integration\n  * CSAT: used for authoring CSAT response comments\n"
          enum:
          - user
          - visitor
          - rule
          - macro
          - API
          - integration
          - CSAT
        custom_fields:
          description: Custom fields for this teammate
          $ref: '#/components/schemas/CustomFieldParameter'
    TeamPreviewResponse:
      type: object
      required:
      - _links
      - id
      - name
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/teams/tim_aqsa
        id:
          type: string
          description: Unique identifier of the team
          example: tim_aqsa
        name:
          type: string
          description: Name of the team
          example: Stanley's crossword puzzle team
  responses:
    listOfInboxes:
      description: Array of Inboxes
      content:
        application/json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    type: string
                    description: Link to resource
                    example: https://yourCompany.api.frontapp.com/inboxes
              _results:
                type: array
                items:
                  $ref: '#/components/schemas/InboxResponse'
    listOfTeams:
      description: Array of teams
      content:
        application/json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    type: string
                    description: Link to resource
                    example: https://yourCompany.api.frontapp.com/teams
              _results:
                type: array
                items:
                  $ref: '#/components/schemas/TeamPreviewResponse'
    listOfTeammates:
      description: Array of teammates
      content:
        application/json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    type: string
                    description: Link to resource
                    example: https://yourCompany.api.frontapp.com/teammates
              _results:
                type: array
                items:
                  $ref: '#/components/schemas/TeammateResponse'
    listOfTeammateGroups:
      description: Array of teammate groups
      content:
        application/json:
          schema:
            type: object
            properties:
              _links:
                type: object
                properties:
                  self:
                    type: string
                    description: Link to resource
                    example: https://yourCompany.api.frontapp.com/teammate_groups
              _results:
                type: array
                items:
                  $ref: '#/components/schemas/TeammateGroupResponse'
    teammateGroup:
      description: A teammate group
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/TeammateGroupResponse'
  securitySchemes:
    http:
      type: http
      scheme: bearer
      bearerFormat: JWT
x-api-id: front
x-explorer-enabled: false
x-proxy-enabled: true
x-samples-enabled: true