openapi: 3.2.0
info:
  version: 0.1.0
  title: Whitespace Platform User API
  description: <div>Last update 29th May 2025</div> <p/> <div>Our intention is to cover the API calls most of use to those wanting  to integrate external systems to the Whitespace Platform. We will give  some descriptions about usage, but put full detail in standalone documents at  <a href='https://apidocs.whitespace.co.uk/'>https://apidocs.whitespace.co.uk/</a>. We intend to have the published endpoints and schemas documented to the  level that the code generated can be used safely and without modification to call our APIs safely.</div>  <p/> <div>Calls exclusive to brokers or underwriters have a comment of Broker Only and Underwriter Only respectively. All other calls work for both, but functionality might depend on the stage the risk is at, or other contextual factors.</div> <div>Where certain properties refer to RootID or similar, they are actually referring to the ID of the entire slip, encompassing all stages and instances of the contract. This is a unique 38-character reference starting with the letters IC. If they mention riskID or docID or placingID, these are refering to the ID of a specific document or contract instance within the slip. This is always the RootID of the base slip followed by a double colon, ::, and further characters.</div> <div> Once your Integration is ready to go live, the URL for production is <b>https://www.whitespaceplatform.com</b></div>
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: <p>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'
  /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'
  /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
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