openapi: 3.2.0
info:
  version: 0.1.0
  title: Whitespace Platform Shared 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: Shared
paths:
  /api/shared/corporate:
    get:
      summary: List of all companies operating on the platform, with teams and users
      description: <p>Note that the users' email addresses are removed for reasons of data protection.</p> <p>This list can be loaded and cached for reference purposes, with a periodic refresh.</p>
      tags:
      - Shared
      responses:
        '200':
          description: array of Company objects
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CorporateDetail'
  /api/shared/compressedCorporate:
    get:
      summary: Returns the full list of corporate data in a compressed format
      description: <p>Please note that to perform the compression, the API call requires the Accept-Encoding header with the value 'deflate'.</p> <p>This list can be loaded and cached for reference purposes, with a periodic refresh.</p>
      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'
  /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
components:
  schemas:
    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
    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