Whitespace Shared API

openapi: 3.2.0
info:
  version: 0.1.0
  title: Whitespace Platform Shared 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: Shared
paths:
  /api/shared/corporate:
    get:
      summary: List of all companies operating on the platform, with teams and users
      description: 'Note that the users'' email addresses are removed for reasons of data protection.


        This list can be loaded and cached for reference purposes, with a periodic refresh.'
      tags:
      - Shared
      responses:
        '200':
          description: array of Company objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorporateDetail'
      operationId: getApiSharedCorporate
      x-operation-id-source: derived
  /api/shared/compressedCorporate:
    get:
      summary: Returns the full list of corporate data in a compressed format
      description: 'Please note that to perform the compression, the API call requires the Accept-Encoding header with the value ''deflate''.


        This list can be loaded and cached for reference purposes, with a periodic refresh.'
      tags:
      - Shared
      parameters:
      - name: Accept-Encoding
        in: header
        required: true
        schema:
          type: string
          enum:
          - deflate
        example: deflate
      responses:
        '200':
          description: Array of Company objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorporateDetail'
      operationId: getApiSharedCompressedCorporate
      x-operation-id-source: derived
  /api/shared/corporate/memberStates:
    get:
      summary: List of values for the state of a member
      tags:
      - Shared
      responses:
        '200':
          description: reference array of values for a mamber's current state
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example:
                - Draft
                - Live
                - Suspended
                - Digitiser
                - ReadOnly
      operationId: getApiSharedCorporateMemberStates
      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'
    ExtendedMRC:
      type: object
      description: JSON returned by getExtendedMRC including the Risk and a broader range of data
      properties:
        createdAt:
          type: string
          example: '2021-08-04T15:18:02.000Z'
        updatedAt:
          type: string
          example: '2021-08-04T15:18:02.000Z'
        type:
          type: string
          example: RWPlacing
          description: RWPlacing in all cases
        control:
          $ref: '#/components/schemas/RWPlacing/properties/control'
        channels:
          type: array
          items:
            type: string
            example: ajc_ALL
        MRCContract:
          $ref: '#/components/schemas/RWPlacing/properties/MRCContract'
        questionnaire:
          type: object
          properties:
            questionnaire:
              type: object
              properties:
                questions:
                  type: array
                  items:
                    type: object
                    properties:
                      tag:
                        type: string
                        example: Pension_Or_Benefits_Plan_Company_Sponsor
                        description: name of the tag
                      text:
                        type: string
                        example: Does the company sponsor any pension or benefits plan?
                        description: The Question text
                      id:
                        type: string
                        example: Pension or Benefits Plan - Company Sponsor
                        description: the id of the question
                      hidden:
                        type: boolean
                        example: true
                        description: If the question is hidden or not, usually because the dependant question has not been answered
                      table:
                        type: array
                        items:
                          type: object
                          properties:
                            tag:
                              type: string
                              example: Asset_Amount_Year
                            text:
                              type: string
                              example: Year
                        required:
                        - tag
                        - text
                    required:
                    - text
                    - id
                    - tag
              required:
              - questions
          required:
          - questionnaire
        proposedEndorsementFollowers:
          type: object
          description: an object where the keys are the carrier team ids and the values are 'unchosen', 'leader', 'agreementParty', 'notifyParty', 'nonNotifyParty'
          properties:
            palermo_ALL:
              description: as an example, the follower status for the Palermo All Risks team
              type: string
              example: leader
        provenance:
          type: object
          description: Meta-data about the document to aid with auditing
          properties:
            version:
              type: string
              description: Version message of the platform system that created the document
              example: 2022-04-11@15:04:48
            dataHash:
              type: string
              description: Data hash of the activity document
              example: 485241de4e5bfc76a0e2ef8bab79350c02d3aa06846fd2996cbf9fc9a7840eb0
            system:
              type: string
              description: The internal name of the platform system
              example: LavAPI
            userID:
              type: string
              description: The user ID of the user whose action generated the document
              example: MUB980AB60-1C96-4092-A1B4-B8FB183360D1
            writtenAt:
              type: string
              description: The creation date of the document, in YYYY-MM-DD hh:mm:ss format
              example: '2022-05-09T11:44:41.000Z'
            provHash:
              type: string
              description: Provisioning hash of the document
              example: 76a209a16d8b9214e7a33483d78718cc1a7e7aed7047282d2c94417404558e2d
        accountDocID:
          type: string
          example: ''
        writtenLineSets:
          type: array
          description: the written lines on the contract
          items:
            $ref: '#/components/schemas/RWWrittenLineSet'
        signedLineSets:
          type: array
          description: the signed lines on the contract
          items:
            $ref: '#/components/schemas/RWSignedLineSet'
        platformReferences:
          type: object
          description: document and revision of the risk
          properties:
            RiskID:
              type: string
              description: the document ID of the risk
              example: IC08B5EC17-5486-4323-82FC-62CC8C410EA0::FO::EN1
            Revision:
              type: string
              description: the revision of the risk
              example: 4-b63141573da07d5316b7a2b4585fbd2b
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT