openapi: 3.0.1
info:
  title: Symphony Agent Add Types 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: Types
paths:
  /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:
      - Types
      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/types:
    get:
      summary: Symphony List All Types
      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: query
        name: status
        schema:
          $ref: '#/components/schemas/Status'
        required: false
        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: listTypes
      tags:
      - Types
      responses:
        '200':
          description: Successful response. Returns the list of all types
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TypeList'
        '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'
  /v1/types/{typeId}:
    get:
      summary: Symphony Retrieve a 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: Type id
        example: SDL
      description: Retrieve a type
      operationId: getType
      tags:
      - Types
      responses:
        '200':
          description: Successful response. Returns the type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Type'
        '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 type id is not found
          $ref: ./symphony-common-definitions.yaml#/components/responses/NotFound
        '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'
    InteractionTransfer:
      properties:
        target:
          type: string
          enum:
          - TO_USER
          - TO_MEMBERS
          - NONE
          description: Only TO_MEMBERS supported now
          example: TO_MEMBERS
        updateInteractionOngroupUpdate:
          type: boolean
        systemMessageOnInteraction:
          type: boolean
          description: Not supported yet
        transferView:
          $ref: '#/components/schemas/TransferView'
        auditTransfer:
          type: boolean
    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'
    MembershipControl:
      properties:
        entitlements:
          type: array
          uniqueItems: true
          items:
            type: string
        manualMembership:
          type: boolean
        ruleMembership:
          type: boolean
          description: Not supported yet
        updateMembershipOnRuleUpdate:
          type: boolean
          description: Not supported yet
        notifyMembersOnUpdate:
          type: boolean
        canBelongToMultipleGroup:
          type: boolean
          description: For the SDL groupe type this flag is true, for the company groupe type it is false
          default: true
    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
    GroupInteractionTransfer:
      description: Group interaction transfer.
      properties:
        restrictedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        restrictedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    TransferView:
      properties:
        visible:
          type: boolean
        restrictToTenants:
          type: boolean
        restrictToUsers:
          type: boolean
          description: Not supported yet
    ProfileControl:
      properties:
        visibilityRestriction:
          $ref: '#/components/schemas/VisibilityRestriction'
        implicitConnection:
          $ref: '#/components/schemas/ImplicitConnection'
        wallSupport:
          type: boolean
          description: Not supported yet
        profileFields:
          type: array
          uniqueItems: true
          items:
            type: string
        searchFields:
          type: array
          uniqueItems: true
          items:
            type: string
        canHavePublicProfile:
          type: boolean
          description: For the SDL groupe type this flag is true, for the company groupe type it is false
          default: true
    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
    VisibilityRestriction:
      properties:
        visible:
          type: boolean
        restrictToTenants:
          type: boolean
          description: Not supported yet
        restrictToUsers:
          type: boolean
          description: Not supported yet
    BaseType:
      description: A reduced set Type object, for retrieving list of types purpose
      properties:
        id:
          type: string
          description: Type identifier
          example: SDL
        ownerType:
          $ref: '#/components/schemas/Owner'
          example: TENANT
        name:
          type: string
          description: Type's name
          example: Symphony Distribution List
        status:
          $ref: '#/components/schemas/Status'
    GroupImplicitConnection:
      description: Group implicit connections.
      properties:
        connectedTenantsList:
          type: array
          items:
            type: integer
          example:
          - 100
        connectedUsersList:
          type: array
          items:
            type: integer
            format: int64
          example:
          - 12345678900000
    TypeList:
      properties:
        pagination:
          $ref: ./symphony-common-definitions.yaml#/components/schemas/Pagination
        data:
          type: array
          items:
            $ref: '#/components/schemas/BaseType'
    Type:
      allOf:
      - $ref: '#/components/schemas/BaseType'
      - type: object
        required:
        - rootCause
        properties:
          profileControl:
            $ref: '#/components/schemas/ProfileControl'
          membershipControl:
            $ref: '#/components/schemas/MembershipControl'
          interactionControl:
            $ref: '#/components/schemas/InteractionControl'
    ImplicitConnection:
      properties:
        all:
          type: boolean
        connectToTenants:
          type: boolean
          description: Not supported yet
        connectToUsers:
          type: boolean
          description: Not supported yet
    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'
    InteractionControl:
      properties:
        allowIMs:
          type: boolean
        allowRooms:
          type: boolean
        interactionTransfer:
          $ref: '#/components/schemas/InteractionTransfer'
        tagStream:
          type: string
        canHaveInteraction:
          type: boolean
          description: For the SDL groupe type this flag is true, for the company groupe type it is false
          default: true
    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:
    TooManyRequests:
      description: Too Many Requests
      content:
        application/json:
          schema:
            $ref: ./symphony-common-definitions.yaml#/components/schemas/Error