openapi: 3.0.1
info:
  title: Symphony Agent Add Groups API
  description: 'This document refers to Symphony API calls to send and receive messages

    and content. They need the on-premise Agent installed to perform

    decryption/encryption of content.


    - sessionToken and keyManagerToken can be obtained by calling the

    authenticationAPI on the symphony back end and the key manager

    respectively. Refer to the methods described in authenticatorAPI.yaml.

    - Actions are defined to be atomic, ie will succeed in their entirety

    or fail and have changed nothing.

    - If it returns a 40X status then it will have sent no message to any

    stream even if a request to some subset of the requested streams

    would have succeeded.

    - If this contract cannot be met for any reason then this is an error

    and the response code will be 50X.

    - MessageML is a markup language for messages. See reference here:

    https://rest-api.symphony.com/docs/messagemlv2

    - **Real Time Events**: The following events are returned when reading

    from a real time messages and events stream ("datafeed"). These

    events will be returned for datafeeds created with the v5 endpoints.

    To know more about the endpoints, refer to Create Messages/Events

    Stream and Read Messages/Events Stream. Unless otherwise specified,

    all events were added in 1.46.

    '
  version: 22.9.1
servers:
- url: /
tags:
- name: Groups
paths:
  /v1/groups/{groupId}/member:
    post:
      summary: Symphony Add a New User to a an Existing Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the origin
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: groupId
        schema:
          type: string
          nullable: false
          description: Group id
          example: WzEwMF1bU0RMXVtUZXN0IEdyb3VwXQ
        required: true
      description: Add a new user to a an existing group
      operationId: addMemberToGroup
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/AddMemberRequestBody'
      responses:
        '200':
          description: Successful response. Returns the group with the new add user as a member
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
        '452':
          description: Returned if there is a violation in info barrier rules. This error is not relevant in case of a Company group
          $ref: '#/components/responses/InfoBarrierViolation'
  /v1/groups:
    post:
      summary: Symphony Insert a New Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      description: Insert a new group into database
      operationId: insertGroup
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/CreateGroupBody'
      responses:
        '201':
          description: Successful response. Returns the group just created with the new added member
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters, Trying to add a member which is already existing within the group list of members, or the requested user member is already a part of company group in case of a company group type
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
        '452':
          description: Returned if there is a violation in info barrier rules. This error is not relevant in case of a Company group
          $ref: '#/components/responses/InfoBarrierViolation'
  /v1/groups/{groupId}:
    get:
      summary: Symphony Retrieve a Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: groupId
        schema:
          type: string
        required: true
        description: Group id
        example: WzEwMF1bU0RMXVtUZXN0IEdyb3VwXQ
      description: Retrieve a group
      operationId: getGroup
      tags:
      - Groups
      responses:
        '200':
          description: Successful response. Returns the group
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if groupId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
    put:
      summary: Symphony Update a Group
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: header
        name: If-Match
        schema:
          type: string
          description: ETag of group to be updated
          example: e3a52e72-0854-4401-8c24-e0b17c0ca304
        required: true
      - in: path
        name: groupId
        schema:
          type: string
        required: true
        description: Group id
        example: 60af77fd294165466ccdf510
      description: Update an existing group
      operationId: updateGroup
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/UpdateGroupBody'
      responses:
        '200':
          description: Successful response. Returns the group just updated
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if groupId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '412':
          description: The update is rejected because concurrent update
          $ref: ./symphony-common-definitions.yaml#/components/responses/PreconditionFailed
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
        '452':
          description: Returned if there is a violation in info barrier rules. This error is not relevant in case of a Company group
          $ref: '#/components/responses/InfoBarrierViolation'
  /v1/groups/{groupId}/avatar:
    post:
      summary: Symphony Update the Group Avatar
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: groupId
        schema:
          type: string
        required: true
        description: Group id
        example: 60af77fd294165466ccdf510
      description: Update the group account avatar
      operationId: updateAvatar
      tags:
      - Groups
      requestBody:
        $ref: '#/components/requestBodies/UpdateAvatar'
      responses:
        '200':
          description: Successful response. Returns the group with the avatar updated
          headers:
            Etag:
              schema:
                type: string
                example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadGroup'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if groupId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
  /v1/groups/type/{typeId}:
    get:
      summary: Symphony List All Groups of Specified Type
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      - in: path
        name: typeId
        schema:
          type: string
        required: true
        description: Group type id
        example: SDL
      - in: query
        name: status
        schema:
          $ref: '#/components/schemas/Status'
        required: false
        description: filter by status, active or deleted. If not specified both are returned
        example: ACTIVE
      - in: query
        name: before
        schema:
          type: string
        required: false
        description: NOT SUPPORTED YET, currently ignored. Cursor that points to the start of the current page of data. If not present, the current page is the first page
      - in: query
        name: after
        schema:
          type: string
        required: false
        description: cursor that points to the end of the current page of data. If not present, the current page is the last page
      - in: query
        name: limit
        schema:
          type: integer
        required: false
        description: numbers of items to return
        example: 100
      - in: query
        name: sortOrder
        schema:
          $ref: '#/components/schemas/SortOrder'
        required: false
        description: items sorting direction (ordered by createdDate)
        example: ASC
      operationId: listGroups
      tags:
      - Groups
      responses:
        '200':
          description: Successful response. Returns the list of all groups
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '404':
          description: Returned if typeId is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
  /v1/groups/deleteAll:
    delete:
      summary: Symphony Delete all data related to the current pod (extracted from JWT). This endpoint is for maintenance/test and it is usually disabled or restricted
      parameters:
      - in: header
        name: X-Symphony-Host
        schema:
          type: string
          description: headers to indentify the originator
          nullable: false
          minLength: 1
          example: localhost.symphony.com
        required: true
      operationId: deleteAllGroups
      tags:
      - Groups
      responses:
        '200':
          description: Successful response. Returns the list of all groups (it should be empty)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupList'
        '400':
          description: Returned if missing required parameters or wrong parameters
          $ref: ./symphony-common-definitions.yaml#/components/responses/BadRequest
        '401':
          description: Returned if wrong or missing JWT token
          $ref: ./symphony-common-definitions.yaml#/components/responses/Unauthorized
        '403':
          description: Returned if JWT token missing the required entitlement
          $ref: ./symphony-common-definitions.yaml#/components/responses/Forbidden
        '429':
          description: Returned if the backend is overloaded
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    GroupList:
      properties:
        pagination:
          $ref: ./symphony-common-definitions.yaml#/components/schemas/Pagination
        data:
          type: array
          items:
            $ref: '#/components/schemas/ReadGroup'
    Member:
      description: A Group member.
      properties:
        memberTenant:
          type: integer
          description: Member's tenant id
          nullable: false
          example: 100
        memberId:
          type: integer
          format: int64
          description: Member's user id
          nullable: false
          example: 12345678900000
    ReadGroup:
      allOf:
      - $ref: '#/components/schemas/BaseGroup'
      - type: object
        required:
        - rootCause
        properties:
          id:
            type: string
            description: Group's unique identifier
          createdDate:
            type: string
            format: date-time
          createdBy:
            type: string
          updatedDate:
            type: string
            format: date-time
          updatedBy:
            type: string
          status:
            $ref: '#/components/schemas/Status'
          eTag:
            type: string
            example: e3a52e72-0854-4401-8c24-e0b17c0ca304
          subType:
            type: string
            enum:
            - COMMUNITY
            - CHANNEL
            description: The type of the company group, This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: COMMUNITY
          referrer:
            type: string
            description: The referring company name. This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: Symphony, referring company name, referring channel partner name
          members:
            type: array
            items:
              $ref: '#/components/schemas/ReadMember'
          profile:
            $ref: '#/components/schemas/Profile'
            description: The profile is not supported for company group, but only works with SDL as group type
          visibilityRestriction:
            $ref: '#/components/schemas/GroupVisibilityRestriction'
          implicitConnection:
            $ref: '#/components/schemas/GroupImplicitConnection'
          interactionTransfer:
            $ref: '#/components/schemas/GroupInteractionTransfer'
    UploadAvatar:
      properties:
        image:
          type: string
          format: byte
          nullable: false
          description: 'The avatar image for the user profile picture.The image must be a base64-encoded .jpg, .png, or .gif. >- Image size limit: 2 MB'
    UpdateGroup:
      allOf:
      - $ref: '#/components/schemas/CreateGroup'
      - type: object
        required:
        - rootCause
        properties:
          id:
            type: string
            description: Group's unique identifier
            nullable: false
            minLength: 1
            example: 60af77fd294165466ccdf510
          status:
            $ref: '#/components/schemas/Status'
          eTag:
            type: string
            example: e3a52e72-0854-4401-8c24-e0b17c0ca304
            nullable: false
            minLength: 1
    Avatar:
      properties:
        size:
          type: string
        url:
          type: string
    BaseGroup:
      description: A reduced set Group object, for retrieving list of group purpose
      properties:
        type:
          type: string
          nullable: false
          minLength: 1
          description: Group type identifier
          example: SDL
        ownerType:
          $ref: '#/components/schemas/Owner'
          nullable: false
        ownerId:
          type: integer
          format: int64
          description: Owner id if the owner type is tenant (podId) or user (userId), otherwise null
          example: 100
        name:
          type: string
          nullable: false
          minLength: 1
          description: Group's name
          example: Test Group
      required:
      - type
      - ownerType
      - ownerId
      - name
    SortOrder:
      type: string
      enum:
      - ASC
      - DESC
      description: Sort query order
      example: ASC
    addMember:
      properties:
        member:
          $ref: '#/components/schemas/Member'
          nullable: false
    GroupInteractionTransfer:
      description: Group interaction transfer.
      properties:
        restrictedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        restrictedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    Status:
      type: string
      enum:
      - ACTIVE
      - DELETED
      description: Status flag to distinguish between active and deleted objects
      example: ACTIVE
    GroupVisibilityRestriction:
      description: Group visibility restriction.
      properties:
        restrictedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        restrictedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    CreateGroup:
      allOf:
      - $ref: '#/components/schemas/BaseGroup'
      - type: object
        required:
        - rootCause
        properties:
          subType:
            type: string
            enum:
            - COMMUNITY
            - CHANNEL
            description: The type of the company group, This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: COMMUNITY
          referrer:
            type: string
            description: The referring company name. This field is mandatory in case of a company group type, but not applicable for Symphony Distribution List
            example: Symphony, referring company name, referring channel partner name
          members:
            type: array
            items:
              $ref: '#/components/schemas/Member'
          profile:
            $ref: '#/components/schemas/BaseProfile'
            description: The profile is not supported for company group, but only works with SDL as group type
            required: true
          visibilityRestriction:
            $ref: '#/components/schemas/GroupVisibilityRestriction'
          implicitConnection:
            $ref: '#/components/schemas/GroupImplicitConnection'
          interactionTransfer:
            $ref: '#/components/schemas/GroupInteractionTransfer'
    GroupImplicitConnection:
      description: Group implicit connections.
      properties:
        connectedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        connectedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    ReadMember:
      allOf:
      - $ref: '#/components/schemas/Member'
      - type: object
        required:
        - rootCause
        properties:
          addedDate:
            description: Date/time when the member has been added in the group in ISO-8601 format (YYYY-MM-DDThh:mm:ss.sZ)
            type: string
            format: date-time
          status:
            description: Some group types (e.g. COMPANY) keep disabled users, flagging them as DISABLED. However, this attribute is not relevant for group types (e.g. SDL) that remove (instead of flag) disabled user from group
            type: string
            enum:
            - ENABLED
            - DISABLED
            example: ENABLED
    Profile:
      allOf:
      - $ref: '#/components/schemas/BaseProfile'
      - type: object
        required:
        - rootCause
        properties:
          id:
            type: string
            description: Profile unique identifier
          avatars:
            type: array
            items:
              $ref: '#/components/schemas/Avatar'
    BaseProfile:
      description: The group's profile. Please note that in case of a company group type, the profile shouldn't be provided when creating a new company and do not exist in case of an existing company group
      properties:
        displayName:
          type: string
          description: The display name in Directory, it is expected to be the same as group name
          nullable: false
          minLength: 1
          example: Test Group
        companyName:
          type: string
          description: The company name is expected to be the same as group company owner
          example: Acme Corporation
        email:
          type: string
          example: testgroup@acme.com
        mobile:
          type: string
          example: +33(0)600000000
        jobTitle:
          type: string
        jobRole:
          type: string
          example: Director
        jobDepartment:
          type: string
        jobDivision:
          type: string
        jobPhone:
          type: string
        jobCity:
          type: string
        industryOfInterest:
          type: array
          items:
            type: string
          example:
          - Services
        assetClassesOfInterest:
          type: array
          items:
            type: string
          example:
          - Equities
        marketCoverage:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - EMEA
        responsibility:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - Escalation
        function:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - Collateral
        instrument:
          type: array
          uniqueItems: true
          items:
            type: string
          example:
          - Equities
    Owner:
      type: string
      enum:
      - PLATFORM
      - TENANT
      - USER
      description: Owner type. Ony TENANT supported now
      example: TENANT
  responses:
    InfoBarrierViolation:
      description: Info barrier violation found between group account's members.
      content:
        application/json:
          schema:
            $ref: ./symphony-common-definitions.yaml#/components/schemas/Error
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: ./symphony-common-definitions.yaml#/components/schemas/Error
  requestBodies:
    CreateGroupBody:
      description: JSON object containing Group info
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateGroup'
    AddMemberRequestBody:
      description: JSON object containing the user member information and the group on which he will be added to
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/addMember'
    UpdateAvatar:
      description: JSON object containing Group avatar
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UploadAvatar'
    UpdateGroupBody:
      description: JSON object containing Group info
      required: true
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateGroup'