openapi: 3.0.3

info:
  title: Contact Notes
  description: "For retrieving and managing contact notes. Please note for historic reasons contacts are often referred to as participants in Actionstep. For information of how to construct requests utilising fieldsets, sorting, paging, filters, and '*includes*', please refer to the API Developer Portal. E&OE."
  version: "1.0"

externalDocs:
  description: API Developer Portal - Constructing API Requests
  url: https://docs.actionstep.com/api-requests/

paths:
  '/contactnotes':
    get:
      description: Returns a collection of contact notes.
      tags:
        - Contact Notes
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PagedContactNotes'

    post:
      description: Create a new contact note.
      tags:
        - Contact Notes
      requestBody:
        $ref: '#/components/requestBodies/CreateContactNote'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactNote'

  '/contactnotes/{id}':
    get:
      description: Returns a single contact note.
      tags:
        - Contact Notes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a contact note.
          required: true
          schema:
            type: integer
            format: int32
          example: 9287
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactNote'

    put:
      description: Update a contact note.
      tags:
        - Contact Notes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a contact note.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      requestBody:
        $ref: '#/components/requestBodies/UpdateContactNote'
      responses:
        '200':
          description: OK.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactNote'

    delete:
      description: Delete a contact note.
      tags:
        - Contact Notes
      parameters:
        - name: id
          in: path
          description: Unique identifier for a contact note.
          required: true
          schema:
            type: integer
            format: int32
          example: 608
      responses:
        '204':
          description: Success, No Content.

components:
  schemas:
    PagedContactNotes:
      type: object
      properties:
        contactnotes:
          type: array
          items:
            $ref: '#/components/schemas/ContactNote'
        meta:
          $ref: '#/components/schemas/PageMetaData'

    PageMetaData:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/PagingData'

    PagingData:
      type: object
      properties:
        contactnotes:
          $ref: '#/components/schemas/ContactNotesPageData'

    ContactNotesPageData:
      type: object
      properties:
        recordCount:
          description: The total number of contact notes returned by the underlying query.
          type: integer
          example: 2487
        pageCount:
          description: The total number of pages generated by the underlying query.
          type: integer
          example: 50
        page:
          description: The page number for this page of contact notes.
          type: integer
          example: 2
        pageSize:
          description: Page size.
          type: integer
          example: 50
        prevPage:
          description: A URL to the previous page of contact notes.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/contactnotes?page=1
        nextPage:
          description: A URL to the next page of contact notes.
          type: string
          example: https://ap-southeast-2.actionstep.com/api/rest/contactnotes?page=3

    ContactNote:
      type: object
      properties:
        id:
          description: Unique identifier for the contact note.
          example: 2347
          type: integer
          readOnly: true
        enteredTimestamp:
          description: The date and time the contact note is entered.
          example: 2022-05-03T00:09:00+12:00
          format: timestamp
          type: string
          readOnly: true
        text:
          description: Content of the contact note.
          example: Please review AML status.
          type: string
        enteredBy:
          description: The Actionstep user who entered the contact note.
          example: Smith, John
          type: string
          readOnly: true
        enteredByParticipant:
          description: Unique identifier of the Actionstep user who created the contact note.
          example: 842
          type: integer
          readOnly: true
        source:
          description: Indicates the source of the contact note.
          enum:
            - System
            - User
          example: User
          type: string
        noteTimestamp:
          description: The date and time for the contact note.
          example: 2023-06-03T00:09:30+12:00
          format: timestamp
          type: string
        links:
          $ref: '#/components/schemas/ContactNoteLinks'

    ContactNoteLinks:
      type: object
      properties:
        participant:
          description: Unique identifier of the contact to whom this note is associated.
          example: 546
          type: integer
          readOnly: true

    CreateContactNote:
      type: object
      required:
        - text
      properties:
        text:
          description: Content of the contact note.
          example: Updated AML status notes.
          type: string
        source:
          description: Indicates the source of the contact note.
          enum:
            - System
            - User
          example: User
          type: string
        noteTimestamp:
          description: The date and time for the contact note.
          example: 2023-06-03T00:09:30+12:00
          format: timestamp
          type: string
        links:
          $ref: '#/components/schemas/CreateContactNoteLinks'

    CreateContactNoteLinks:
      type: object
      required:
        - participant
      properties:
        participant:
          description: Unique identifier of the contact to whom the note is associated.
          example: 546
          type: integer

    UpdateContactNote:
      type: object
      required:
        - text
      properties:
        text:
          description: Content of the contact note.
          example: Updated address details.
          type: string
        noteTimestamp:
          description: The date and time for the contact note.
          example: 2023-06-03T00:09:30+12:00
          format: timestamp
          type: string
        links:
          $ref: '#/components/schemas/UpdateContactNoteLinks'

    UpdateContactNoteLinks:
      type: object
      properties:
        participant:
          description: Unique identifier of the contact to whom the note is associated.
          example: 546
          type: integer

  requestBodies:
    CreateContactNote:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateContactNote'

    UpdateContactNote:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/UpdateContactNote'