openapi: 3.2.0
info:
  title: placement Programme API
  description: "This API collection provides the capability to manage aspects of the Placement structure. \nThis includes that overall management of Placements, Programmes, Contracts as well as any Sections within a Contract. This also includes the ability to set up carrier/underwriter participants for insurance placement purposes."
  version: '1'
servers:
- url: https://sand-api.londonmarketgroup.co.uk/ppl/nextgen/placements
  description: Joint Integration testing (JIT2) environment
tags:
- name: programme
  description: Enables the creation and management of Programme structures within a Placement. This also includes the capability to add existing Contracts into a programme.
paths:
  /placements/{placementId}/programmes:
    post:
      tags:
      - programme
      description: Creates a Programme record under the Placement structure. This enables the grouping of Contract records that address a common insurance purpose. Contracts can be added at the time of creation.
      operationId: Programme_Post_v1
      parameters:
      - name: X-Auth-Impersonated-User
        in: header
        description: The email address of the Requesting User or the Impersonated User.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$
      - name: X-Auth-Team
        in: header
        description: A system-generated unique identifier for a Broker Team, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: placementId
        in: path
        description: A system-generated unique identifier for a Placement, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      requestBody:
        description: A collection of Contracts for a common purpose. Programme structure for creation and updates.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/programme_post'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/programme_getbyid'
        '400':
          description: Mandatory header parameter is missing from the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '404':
          description: Invalid team or user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '414':
          description: The maximum field length of the URI provided for the request has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
      x-codegen-request-body-name: programme
  /placements/{placementId}/programmes/{programmeId}:
    get:
      tags:
      - programme
      description: Returns the Programme structure for a specified Programme record. This will return information about the Programme and  summarised information about Contract records within the Programme structure.
      operationId: Programme_GetById_v1
      parameters:
      - name: X-Auth-Impersonated-User
        in: header
        description: The email address of the Requesting User or the Impersonated User.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$
      - name: X-Auth-Team
        in: header
        description: A system-generated unique identifier for a Broker Team, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: placementId
        in: path
        description: A system-generated unique identifier for a Placement, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: programmeId
        in: path
        description: A system-generated unique identifier for a Programme, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/programme_getbyid'
        '400':
          description: Mandatory header parameter is missing from the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '404':
          description: Invalid team or user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '414':
          description: The maximum field length of the URI provided for the request has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
    put:
      tags:
      - programme
      description: Updates a Programme record. Contracts can be added into the Programme structure.
      operationId: Programme_Put_v1
      parameters:
      - name: X-Auth-Impersonated-User
        in: header
        description: The email address of the Requesting User or the Impersonated User.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$
      - name: X-Auth-Team
        in: header
        description: A system-generated unique identifier for a Broker Team, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: X-Last-Modified
        in: header
        description: The date timestamp to be used to validate an update operation.
        required: true
        schema:
          type: string
          format: date-time
        example: '2014-12-31T23:59:59.938Z'
      - name: placementId
        in: path
        description: A system-generated unique identifier for a Placement, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: programmeId
        in: path
        description: A system-generated unique identifier for a Programme, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      requestBody:
        description: A collection of Contracts for a common purpose. Programme structure for creation and updates.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/programme_put'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/programme_getbyid'
        '400':
          description: Mandatory header parameter is missing from the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '404':
          description: Invalid team or user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '414':
          description: The maximum field length of the URI provided for the request has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
      x-codegen-request-body-name: programme
    delete:
      tags:
      - programme
      description: Deletes a Programme record, where the record is in a state that enables its deletion. Any Contract records that exist in this Programme will be moved into the default Programme.
      operationId: Programme_Delete_v1
      parameters:
      - name: X-Auth-Impersonated-User
        in: header
        description: The email address of the Requesting User or the Impersonated User.
        schema:
          type: string
          pattern: ^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$
      - name: X-Auth-Team
        in: header
        description: A system-generated unique identifier for a Broker Team, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: placementId
        in: path
        description: A system-generated unique identifier for a Placement, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      - name: programmeId
        in: path
        description: A system-generated unique identifier for a Programme, with a format and structure defined by the technology used.
        required: true
        schema:
          type: string
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      responses:
        '200':
          description: ''
          content: {}
        '400':
          description: Mandatory header parameter is missing from the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '401':
          description: Authentication error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '404':
          description: Invalid team or user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '414':
          description: The maximum field length of the URI provided for the request has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '429':
          description: Too many requests.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error_document'
components:
  schemas:
    metadata_user:
      required:
      - user_email
      type: object
      properties:
        user_email:
          type: string
          description: The email address of the User.
          default: ''
        first_name:
          type: string
          description: The first name of the User.
          default: ''
        last_name:
          type: string
          description: The last name of the User.
          default: ''
      additionalProperties: false
      description: The User information of the Metadata User.
    metadata:
      required:
      - created_by
      - created_channel
      - created_date
      - modified_by
      - modified_channel
      - modified_date
      type: object
      properties:
        created_date:
          type: string
          description: The date and timestamp when the entity was created.
          format: date-time
          example: '2014-12-31T23:59:59.938Z'
        created_channel:
          type: string
          description: The mechanism used to create the entity, e.g. OutSystems, API
          default: ''
        created_by:
          $ref: '#/components/schemas/metadata_user'
        modified_date:
          type: string
          description: The date and timestamp when the entity was modified.
          format: date-time
          example: '2014-12-31T23:59:59.938Z'
        modified_channel:
          type: string
          description: The mechanism used to modify the entity, e.g. OutSystems, API
          default: ''
        modified_by:
          $ref: '#/components/schemas/metadata_user'
      additionalProperties: false
      description: A collection of data items to support the creation and update of record entities.
    programme_contract_getbyid:
      required:
      - contract_id
      - unique_market_reference
      type: object
      properties:
        contract_id:
          type: string
          description: A system-generated unique identifier for a Contract, with a format and structure defined by the technology used.
          default: ''
        unique_market_reference:
          type: string
          description: The reference allocated by the broker to identify the Contract for use within the placement process, as a concatenation of the Broker Code and Broker Contract Reference.
          default: ''
      additionalProperties: false
      description: A collection of insurance Contracts.
    broker_user:
      required:
      - first_name
      - last_name
      - user_email
      type: object
      properties:
        user_email:
          type: string
          description: The email address of the User.
          default: ''
        first_name:
          type: string
          description: The first name of the User.
          default: ''
        last_name:
          type: string
          description: The last name of the User.
          default: ''
      additionalProperties: false
      description: The User information of the responsible Broker User.
    error:
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          description: The error message.
        argument:
          type:
          - string
          - 'null'
          description: The syntax argument used to validate the field against (if on syntax validation).
        field:
          type:
          - string
          - 'null'
          description: The field where the error occurred (if field specific).
        code:
          type: string
          description: The error code.
    error_document:
      type: object
      description: The error document.
      properties:
        errors:
          type: array
          description: A collection of errors. The list may be empty.
          items:
            $ref: '#/components/schemas/error'
    broker_team_company:
      required:
      - company_name
      - team_id
      - team_name
      type: object
      properties:
        team_id:
          type: string
          description: A system-generated unique identifier for a Broker Team, with a format and structure defined by the technology used.
          default: ''
        team_name:
          type: string
          description: The name of the Broker Team, as defined by the broker organisation.
          default: ''
        company_name:
          type: string
          description: Name of the Company the User belongs to.
          default: ''
      additionalProperties: false
      description: The team information of the Broker Team responsible for the node.
    programme_post:
      required:
      - description
      - user_email
      type: object
      properties:
        description:
          type: string
          description: A description of the Programme supplied by the Broker.
          default: ''
          pattern: ^.{1,256}$
        user_email:
          type: string
          description: The User information of the Broker User responsible for the Programme. The email address of the User.
          default: ''
          pattern: ^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$
        add_contracts:
          type: array
          description: A collection of insurance Contracts to be added to the Programme.
          items:
            $ref: '#/components/schemas/programme_contract_postput'
      additionalProperties: false
      description: Programme structure for creates
    programme_getbyid:
      required:
      - broker_team
      - broker_user
      - default
      - description
      - earliest_inception_date
      - metadata
      - placement_id
      - programme_id
      - sequence_number
      - status
      type: object
      properties:
        programme_id:
          type: string
          description: A system-generated unique identifier for a Programme, with a format and structure defined by the technology used.
          default: ''
        placement_id:
          type: string
          description: A system-generated unique identifier for a Placement, with a format and structure defined by the technology used.
          default: ''
        default:
          type: boolean
          description: Identifies whether this is a default Programme. A default Programme is a programme data structure where Contracts that are not within a business-related Programme are maintained.
          example: false
        sequence_number:
          type: integer
          description: The sequence number in which differing Programmes are ordered.
          format: int32
          example: 0
        broker_team:
          $ref: '#/components/schemas/broker_team_company'
        broker_user:
          $ref: '#/components/schemas/broker_user'
        description:
          type: string
          description: A description of the Placement supplied by the Broker.
          default: ''
        earliest_inception_date:
          type: string
          description: The earliest inception date of all Contracts contained within the Programme structure.
          format: date
          example: '2014-12-31'
        status:
          type: string
          description: The code that represents the Programme status.
          default: ''
        metadata:
          $ref: '#/components/schemas/metadata'
        contracts:
          type: array
          description: A collection of insurance Contracts.
          items:
            $ref: '#/components/schemas/programme_contract_getbyid'
      additionalProperties: false
      description: A collection of Contracts for a common purpose.
    programme_put:
      required:
      - description
      - user_email
      type: object
      properties:
        description:
          type: string
          description: A description of the Programme supplied by the Broker.
          default: ''
          pattern: ^.{1,256}$
        user_email:
          type: string
          description: The User information of the Broker User responsible for the Programme. The email address of the User.
          default: ''
          pattern: ^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$
        add_contracts:
          type: array
          description: A collection of insurance Contracts to be added to the Programme.
          items:
            $ref: '#/components/schemas/programme_contract_postput'
      additionalProperties: false
      description: Programme structure for updates
    programme_contract_postput:
      required:
      - contract_id
      type: object
      properties:
        contract_id:
          type: string
          description: A system-generated unique identifier for a Contract, with a format and structure defined by the technology used.
          default: ''
          pattern: ^[0-9a-fA-F]{8}-([0-9a-fA-F]{4}-){3}[0-9a-fA-F]{12}$
      additionalProperties: false
      description: ''