openapi: 3.2.0
info:
  version: 0.1.0
  title: Whitespace Platform Attachments 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: Attachments
paths:
  /api/attachments/{corporate}/{logo}:
    get:
      tags:
      - Attachments
      summary: Get a logo for the corporate (broker or carrier) on the system
      parameters:
      - in: path
        name: corporate
        schema:
          type: string
        required: true
        description: The corporate company id, uppercase and prefixed by 'Corporate-
        example: Corporate-BLACKPOOL
      - in: path
        name: logo
        schema:
          type: string
        required: true
        description: Either logocolour for a coloured logo, or logobw for a black-and-white one
        example: logocolour
      responses:
        '200':
          description: a logo, not as JSON, usually in PNG format
        '401':
          $ref: '#/paths/~1api~1risks~1save/post/responses/401'
  /api/attachments/{rootID}:
    get:
      tags:
      - Attachments
      parameters:
      - in: path
        name: rootID
        schema:
          type: string
        required: true
        description: The unique ID of the risk
        example: IC213DA609-D6B5-4A05-86B8-3FD91E861F57
      summary: Gets meta data for all attachments available on a risk
      responses:
        '200':
          description: <p>The meta data for all attachments available on the risk. Note that the parentDocID and identifier are the values used in GET /api/attachments/$parentDocID/$identifier to retrieve the content of the attachment.</p>
          content:
            application/json:
              example:
              - attachedAt: '2022-10-10 16:26:09'
                attachedByUser: MU5F640CA3-FEEF-4E18-BAA0-EB9375824F68
                attachmentName: SiteMap.png
                channels:
                - blackpool_PROPERTY
                content_type: application/octet-stream
                digest: sha1-PQdi0wPAzykWJ+J4yjVIxrvsj30=
                identifier: A-6825C239-CDB3-429F-B53C-24058533F20A
                length: 767008
                parentDocID: IC8248761E-ABDF-4B52-B484-DF6174364694::ATCH::A-6825C239-CDB3-429F-B53C-24058533F20A
                version: 1
              schema:
                type: array
                items:
                  type: object
                  properties:
                    attachedAt:
                      type: string
                      example: '2022-10-10T16:26:09.000Z'
                    attachedByUser:
                      type: string
                      example: MU5F640CA3-FEEF-4E18-BAA0-EB9375824F68
                      description: the unique MU number for the user who uploaded the attachment
                    channels:
                      type: array
                      items:
                        type: string
                        example: blackpool_PROPERTY
                    content_type:
                      type: string
                      example: application/octet-stream
                    digest:
                      type: string
                      example: sha1-PQdi0wPAzykWJ+J4yjVIxrvsj30=
                    identifier:
                      type: string
                      example: A-6825C239-CDB3-429F-B53C-24058533F20A
                      description: use this value in a call to /api/attachments/$parentDocID/$identifier
                    length:
                      type: integer
                      example: 767008
                    parentDocID:
                      type: string
                      example: IC8248761E-ABDF-4B52-B484-DF6174364694::ATCH::A-6825C239-CDB3-429F-B53C-24058533F20A
                      description: use this value in a call to /api/attachments/$parentDocID/$identifier
                    version:
                      type: integer
                      example: 1
        '401':
          $ref: '#/paths/~1api~1risks~1save/post/responses/401'
  /api/attachments/array/{rootID}:
    get:
      tags:
      - Attachments
      parameters:
      - in: path
        name: rootID
        schema:
          type: string
        required: true
        description: The unique ID of the risk
        example: IC213DA609-D6B5-4A05-86B8-3FD91E861F57
      summary: Gets meta data for all attachments on a risk
      responses:
        '200':
          description: An array of attachment meta data. This was provided as an alternative to /attachments as an alternative format that may be easier to consume.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    length:
                      type: integer
                      format: int32
                      example: 211059
                    digest:
                      type: string
                      example: sha1-gc50j2LK51yS93Y2HC4S7PQ+xg8=
                    revpos:
                      type: integer
                      format: int32
                      example: 2
                    identifier:
                      type: string
                      example: A-C6FC8D21-A7CE-498D-B08A-F7B0AB23B64D.pdf
                    stub:
                      type: boolean
                      example: true
                    docID:
                      type: string
                      description: the id of the attachment document
                      example: ICC0D79D92-AA39-4624-8B96-188925A9B73E::ATCH
                    metadata:
                      type: object
                      properties:
                        attachedAt:
                          type: string
                          example: '2019-11-18T14:17:54.000Z'
                        attachedByUser:
                          type: string
                          example: MUD38EC011-780A-42D3-94DA-FD9063F5DAF9
                        identifier:
                          type: string
                          example: A-C6FC8D21-A7CE-498D-B08A-F7B0AB23B64D.pdf
                        attachmentName:
                          type: string
                          example: Aviation Demo Slip.pdf
                    content_type:
                      type: string
                      example: application/pdf
              example:
              - attachedAt: '2023-02-14 14:51:00'
                attachedByUser: MU5F640CA3-FEEF-4E18-BAA0-EB9375824F68
                attachmentName: LossHistory.xlsx
                channels:
                - blackpool_MARINE
                content_type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
                digest: sha1-YOPp9u6xEkGQW1EGpErvxoBAxs0=
                identifier: A-6690DC47-A84D-4EC2-9C5C-92F12307A41E
                length: 9244
                parentDocID: IC3F18C8EC-E6F4-4C93-A894-09259B312D13::ATCH::A-6690DC47-A84D-4EC2-9C5C-92F12307A41E
                version: 1
              - attachedAt: '2023-02-14 14:51:10'
                attachedByUser: MU5F640CA3-FEEF-4E18-BAA0-EB9375824F68
                attachmentName: Floorplan.png
                channels:
                - blackpool_MARINE
                content_type: image/png
                digest: sha1-iFd1D6xZBF4j9NNcmxr7DxArppQ=
                identifier: A-37D4FAD6-2E86-4BBD-917F-8CB996671173
                length: 369396
                parentDocID: IC3F18C8EC-E6F4-4C93-A894-09259B312D13::ATCH::A-37D4FAD6-2E86-4BBD-917F-8CB996671173
                version: 1
        '401':
          $ref: '#/paths/~1api~1risks~1save/post/responses/401'
  /api/attachments/{parentDocID}/{identifier}:
    get:
      summary: Get an attachment
      description: <p>Download an attachment, using values from a call to /api/attachments/$RiskID. The content will not be JSON, but the contents of the attachment which can be saved to a file.</p> <p>Due to limitations in Swagger, the attachment might not display properly when tested, but all attachment types can be downloaded normally outside Swagger.</p> <p>If you want to download an attachment linked to a Subjectivity, you need to grab the <b>_id</b> and <b>identifier</b> by calling /api/risks/{rootID}/related/{type} with a type of RWSubjectivityResponse.</p>
      tags:
      - Attachments
      parameters:
      - in: path
        name: parentDocID
        schema:
          type: string
        required: true
        description: The RWAttachmentCollection document, which is parentDocID in a call to /api/attachments/$RiskID -- <b>OR</b>, for Subjectivity Attachments, grab the <b>_id</b> from /api/risks/{rootID}/related/{type} with a type of RWSubjectivityResponse.
        example: IC88965CED-A84B-42F3-8D42-A3534DB92B08::ATCH::A-2343226A-631E-4A1B-A89E-6FBEEFE0E5F3
      - in: path
        name: identifier
        schema:
          type: string
        required: true
        description: The unique id of the attachment, which is <b>identifier</b> in a call to /api/attachments/$RiskID -- <b>OR</b>, for Subjectivity Attachments, grab the <b>_id</b> from /api/risks/{rootID}/related/{type} with a type of RWSubjectivityResponse.
        example: A-2343226A-631E-4A1B-A89E-6FBEEFE0E5F3
      responses:
        '200':
          description: The content of the file, which will not be JSON, but more likely an image, spreadsheet etc.
  /api/attachments/{riskID}/{attachmentName}:
    post:
      summary: Upload an attachment - Broker Only
      description: <p>Broker users can call this endpoint to upload an attachment document to a risk. The document is not automatically shared with carriers. The broker must deliberately share it as required.</p> <p>The payload is not JSON, but the binary content of the file. The MIME Content header must correctly define the file, so "image/png" for an image, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" for an XLSX spreadsheet and so on. All content headers should match the <a href='https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types'>reference list of MIME types at mozilla.org</a>. <p>If you want to replace an existing attachment, use the <b>newVersionOf</b> parameter<p> <p>Please note that underwriter users may call POST /api/attachbyunderwriter to send a contract attachment to the broker.</p>
      tags:
      - Attachments
      parameters:
      - in: path
        name: riskID
        schema:
          type: string
        required: true
        description: The root ID of the risk, starting IC
        example: ICBC2860DE-3E55-40CD-99B8-5457E11D8C0A
      - in: path
        name: attachmentName
        schema:
          type: string
        required: true
        description: A helpful name for the attached document. Often (but not necessarily) the original file name.
        example: AerialPhoto.png
      - in: query
        name: newVersionOf
        schema:
          type: string
        required: false
        description: The ID of the existing attachment you want to replace
        example: A-8652873F-40C7-4667-9A4A-CDD968C55E93
      responses:
        '200':
          description: The response after succesfully uploading an attachment
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    example: Attachment uploaded.
                    description: A message indicating success
  /api/attachments/{rootID}/showToCarriers:
    post:
      summary: Show an attachment to carriers - Broker Only
      tags:
      - Attachments
      parameters:
      - in: path
        name: rootID
        schema:
          type: string
        required: true
        description: The unique root ID of the risk.
        example: IC213DA609-D6B5-4A05-86B8-3FD91E861F57
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                docID:
                  type: string
                  description: the ID of the attachment document.
                  example: ICA3C8F0A7-D477-4FB9-AEB2-52AC2B63C6FA::ATCH::A-3F7233A7-038A-4051-8860-154C7B3C543D
                attachID:
                  type: string
                  description: the ID of the attachment.
                  example: A-3F7233A7-038A-4051-8860-154C7B3C543D
                channels:
                  type: array
                  description: The channels of the carriers you want to show to.
                  items:
                    type: string
                  example:
                  - tomyunderwriting_ALL
      responses:
        '200':
          description: Response from succesfully showing an attachment to a carrier.
          content:
            application/json:
              schema:
                type: object
                properties:
                  msg:
                    type: string
                    description: Message to confirm the attachment has been shown.
                    example: Attachment Shown
  /api/attachbyunderwriter/{riskID}/{underwriter_channel}/{attachmentname}:
    post:
      summary: Upload an Attachment as an Underwriter - Underwriter Only
      description: This call allows an Underwriter account to attach a document to a specific contract. Note that the attachment is automatically shared with the broker when uploaded. The example given below only works with png files due to the objects specified in the requestBody array, but any file type can be attached via API.
      tags:
      - Attachments
      parameters:
      - in: path
        name: riskID
        schema:
          type: string
        required: true
        description: The unique ID of the risk
        example: IC213DA609-D6B5-4A05-86B8-3FD91E861F57
      - in: path
        name: underwriter_channel
        schema:
          type: string
        required: true
        description: The channel name of the underwriter team that the contract is in
        example: whitesails_ALL
      - in: path
        name: attachmentname
        schema:
          type: string
        required: true
        description: The name of file to attach
        example: example.png
      requestBody:
        content:
          image/png:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: The response after succesfully uploading an attachment
          content:
            application/json:
              schema:
                type: object
                properties:
                  docID:
                    type: string
                    description: the document ID
                    example: IC7B4C4ECF-5340-4A88-B5BE-A4ECE8859B61::CHAT::50E4EB6C-147B-4337-8FB7-B4051D42410F
                  attachmentRequestID:
                    type: string
                    example: AR::MUB70853CF-3221-4FD4-8A30-12B05EAD2EA5::83DC9DD9-AEA7-41E5-8777-ADF1BAEFD67F
                  attachmentID:
                    type: string
                    description: The ID of the new attachment
                    example: A-22E24B43-38B7-4B86-B62A-8018DC8B9839
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT