Whitespace User API

openapi: 3.2.0
info:
  version: 0.1.0
  title: Whitespace Platform User API
  description: 'Last update 29th May 2025


    Our intention is to cover the API calls most of use to those wanting to integrate external systems to the Whitespace Platform.'
servers:
- description: Sandbox Environment
  url: https://sandbox.whitespace.co.uk/
- description: Tess Environment
  url: https://tess.whitespace.co.uk/
- description: Beta Environment
  url: https://beta.whitespace.co.uk/
- description: Staging Environment
  url: https://staging.whitespace.co.uk/
security:
- bearerAuth: []
tags:
- name: User
paths:
  /api/user/colleagues:
    get:
      summary: List of all colleagues on the Corporate for the user
      description: Note adding e.g. /Live to the URL lists those in a particular state
      tags:
      - User
      responses:
        '200':
          description: list of other users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorporateDetail/properties/members/items'
      operationId: getApiUserColleagues
      x-operation-id-source: derived
  /api/user/colleagues/{state}:
    get:
      summary: List of all colleagues on the Corporate for the user in a particular state
      tags:
      - User
      parameters:
      - in: path
        name: state
        schema:
          type: string
        required: true
        description: Live, Draft, Suspended etc
        example: Live
      responses:
        '200':
          description: list of other users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorporateDetail/properties/members/items'
      operationId: getApiUserColleaguesByState
      x-operation-id-source: derived
  /api/user/myDetails:
    get:
      tags:
      - User
      summary: gets information about the logged-in user
      responses:
        '200':
          description: information about the user
          content:
            application/json:
              schema:
                type: object
                properties:
                  companyId:
                    type: string
                    description: unique uppercase short name for the user's company
                    example: BLACKPOOL
                  username:
                    type: string
                    description: email address for the user
                    example: sarah.klau.blackpool@wspt.co.uk
                  companyName:
                    type: string
                    description: full name for the user's company
                    example: Blackpool Broking Ltd
                  uniqueID:
                    type: string
                    description: unique code, starting MU, which identifies the user
                    example: MU5F640CA3-FEEF-4E18-BAA0-EB9375824F68
                  teams:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                          description: team name
                          example: Marine Risks excl Liability
                        teamId:
                          type: string
                          description: uppercase short name for the team, used elsewhere as an identifier
                          example: MARINE
                        channel:
                          type: string
                          description: combination of lowercase companyId then teamId
                          example: blackpool_MARINE
      operationId: getApiUserMyDetails
      x-operation-id-source: derived
components:
  schemas:
    CorporateDetail:
      type: object
      properties:
        admins:
          type: array
          description: List of user emails for administrators at the company
          items:
            type: string
            example: sarah.kay.blackpool@wspt.co.uk
        updatedAt:
          type: string
          description: The date and time the company's details were last updated
          example: '2020-02-24T15:32:50.000Z'
        teams:
          type: array
          items:
            type: object
            properties:
              teamId:
                type: string
                description: Team identifier using uppercase letters with no punctuation
                example: MARINECARGO
              secondApprovalReviewers:
                type: array
                items:
                  type: string
                  description: Deprecated (see permissions array below). This array will always be empty. Formerly held userIDs of users with Internal Reviewer permission
                  example: '-'
              secondApprovalSelfApprovers:
                type: array
                items:
                  type: string
                  description: Deprecated (see permissions array below). This array will always be empty. Formerly held userIDs of users with Self-Approver permission
                  example: '-'
              name:
                type: string
                description: The name of the team, usually relating to the class of business worked on
                example: Marine Cargo
              channel:
                type: string
                description: The system channel for the team, comprising a lowercase version of the company ID, followed by underscrore and the team id
                example: blackpool_MARINECARGO
              isInactive:
                type: boolean
                example: false
                description: True if the team has been marked as inactive
              classOfBusiness:
                type: array
                items:
                  type: string
                  example: Marine
                  description: The class(es) of business that are associated with the team
        createdAt:
          type: string
          description: Time and date of creation
          example: '2020-02-24 15:32:50'
        companyId:
          type: string
          description: Company identifier using uppercase letters with no punctuation
          example: OFFLINEBRITISHMARINE
        isTestOnly:
          type: boolean
          description: True if the company account is just a test account with no live database access
          example: false
        channels:
          type: array
          description: Array with just one item, shared channel
          items:
            type: string
            description: The value 'shared'
            example: shared
        stamps:
          type: array
          description: For (re)insurers, lists the stamps they have set up on the system. Empty for brokers
          items:
            type: object
            properties:
              bureauMarket:
                type: string
                example: Lloyd's
              bureauMarketCode:
                type: string
                example: '1444'
              bureauSubMarket:
                type: string
                example: PSM1
              businessUnit:
                type: string
                example: Lloyd's Syndicate No.1444
              stampType:
                type: string
                example: lloyds
              uniqueID:
                type: string
                example: ST1843A345-1F69-435D-84E9-187BB3DD0F23
        buttonStamps:
          type: object
          properties:
            active:
              type: boolean
              example: true
              description: True if the button stamp is available for users to apply
            bureauMarketCode:
              type: string
              example: 5307/5
            companyName:
              type: string
              example: Tomy
            iconOnStamp:
              type: boolean
              description: True if an icon of any type is shown on the stamp, icon type is specified by stampType
              example: true
            layout:
              type: object
              description: The placement of name, type, and code data on the button stamp, each appearing once across the bottom, center, and top slots of the stamp
              properties:
                bottom:
                  type: string
                  enum:
                  - name
                  - type
                  - code
                center:
                  type: string
                  enum:
                  - name
                  - type
                  - code
                top:
                  type: string
                  enum:
                  - name
                  - type
                  - code
            stampID:
              type: string
              example: BTN-BAB19551-5557-4E6B-888B-E3B1B6A0E982
              description: The unique ID of the button stamp, which always starts with BTN
            stampType:
              type: string
              description: The type of icon displayed on the stamp. Note that other indicates no icon
              enum:
              - lloyds
              - brexit
              - other
        settings:
          type: object
          properties:
            canViewOfflineTeams:
              type: boolean
              description: True if the broking organisation is configured to save off-platform lines
              example: false
            mandatoryAuthStages:
              type: array
              items:
                type: string
                description: The list of contract stages at which second approval is required before a contract can proceed
                example: brFirmOrder
            digitiseOnlyToTemplate:
              type: boolean
              example: true
              description: True if the broking organisation can only digitise imported contract files as templates
        isOffline:
          type: boolean
          description: True for company accounts that are offline placeholders for organisations not yet using the platform
          example: false
        _id:
          type: string
          description: Reference ID for this company document
          example: Corporate-BLACKPOOL
        _rev:
          type: string
          description: Currect revision ID for this document
          example: 3-a1df22093d0dc2978b87f396be3cd2fa
        name:
          type: string
          description: The name of the company
          example: Blackpool Insurance Brokers Ltd
        role:
          type: string
          description: The organisation's role on the platform, either 'broker' or 'underwriter'
          example: underwriter
        authorityDetails:
          type: array
          items:
            type: object
            properties:
              authority:
                type: string
                example: Lloyd's (Syndicate Number)
              pseudonymn:
                type: string
                example: '131'
              registrationNumber:
                type: string
                example: '12313'
        members:
          type: array
          items:
            type: object
            description: A user on the platform
            properties:
              name:
                type: string
                description: the user's name
                example: Sarah Kay
              email:
                type: string
                description: <p>email address for the user</p> <p>Note that for Data Protection reasons, the email is removed from some outputs, such as the /api/shared/corporate list. In these cases it can be removed by a call to /api/documents/Corporate-{CompanyID}.</p>
                example: sarah.kay.blackpool@wspt.co.uk
              currentState:
                type: string
                description: Live, Draft, Suspended etc
                example: Live
              uniqueID:
                type: string
                description: Live, Draft, Suspended etc
                example: MUDA8AF5A8-98DF-4EF2-B2B8-4E069EDB7E8C
              allowReporting:
                type: boolean
                description: whether or not the user may run the management reports
                example: true
              isOffPlatform:
                type: boolean
                description: indicates the user is "off platform"s
                example: false
              teams:
                type: array
                items:
                  type: string
                  description: list of teams the user belongs to
                example:
                - blackpool_MARINEHULL
                - blackpool_MARINECARGO
        permissions:
          type: object
          properties:
            secondApprovalReviewers:
              type: object
              properties:
                teams:
                  type: object
                  properties:
                    teamID:
                      type: array
                      description: PLEASE NOTE the key-value of teamID above is just an indicative placeholder and will in practice be the teamID of one of the organisation's teams
                      items:
                        type: string
                        example: MU6E391615-CFF5-4E8E-B9D2-B0DE03BACA0
                        description: The list of userID's of the team's members with Internal Reviewer permission
            secondApprovalSelfApprovers:
              type: object
              properties:
                teams:
                  type: object
                  properties:
                    teamID:
                      type: array
                      description: PLEASE NOTE the key-value of teamID above is just an indicative placeholder and will in practice be the teamID of one of the organisation's teams
                      items:
                        type: string
                        example: MU6E391615-CFF5-4E8E-B9D2-B0DE03BACA0
                        description: The list of userID's of the team's Internal Reviewers who also have the Self Approver permission
            templateManagers:
              type: object
              properties:
                teams:
                  type: object
                  properties:
                    teamID:
                      type: array
                      description: PLEASE NOTE the key-value of teamID above is just an indicative placeholder and will in practice be the teamID of one of the organisation's teams
                      items:
                        type: string
                        example: MU6E391615-CFF5-4E8E-B9D2-B0DE03BACA0
                        description: The list of userID's of the team's members who have the Template Manager permission. This permission is only available to broking organisations
        channelPrefix:
          type: string
          description: A lowercase version of companyId used for the beginning of team channels
          example: blackpool
        provenance:
          $ref: '#/components/schemas/ExtendedMRC/properties/provenance'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT