swagger: '2.0'
info:
  x-ibm-name: ndis-servicebookings
  title: NDIS ServiceBookings
  version: 4.0.0
  description: Digital Partners can create, maintain and delete service bookings
  contact:
    name: NDIA Support Team
    email: api.support@ndis.gov.au
schemes:
  - https
host: api.ndis.gov.au
basePath: /sharedservices/ndis-api/ndis/4.0/service-bookings
consumes:
  - application/json
produces:
  - application/json
security:
  - clientIdHeader: []
securityDefinitions:
  clientIdHeader:
    type: apiKey
    in: header
    name: X-IBM-Client-Id
    description: 'apiKey provided during registration. Max Length(64). example: aa111aa-11a1-1a11-111a-1a1a11aa111a'
x-ibm-configuration:
  testable: true
  enforced: true
  cors:
    enabled: true
  phase: realized
  type: rest
  servers:
    - url: https://api.ndis.gov.au/sharedservices/ndis-api/ndis/4.0/service-bookings
      description: ''
      type:
        - production
        - development
    - url: https://api.ndis.gov.au/sharedservices/ndis-api/ndis/4.0/service-bookings
      description: ''
      type:
        - production
        - development
paths:
  /:
    post:
      summary: Create a new service booking request
      description: |-
        This operation will allow Digital Partners to create two types of Service Bookings, depending on the participant's plan. The types available are Standard Booking and Plan Managed Booking. Standard Booking is available when funds are Agency Managed. Plan Managed Booking is only available to Plan Managers. 

        In order to get a successful response ensure that 
         1. The Service Booking is being created for Support(s) you are registered to provide. 
         2. There is sufficient budget available in the participant's plan. 
         3. The start and end dates of the SB sit within the start and end dates of the participant's plan. 
         4. For Plan Managed Service Bookings, a Standard Service Booking under CB Choice and Control must first exist between the Plan Manager and the Participant. 
         5. If a participant has a stated item, the stated item must be selected together with the support category.
         6. Declare that this Service Booking has been discussed with and agreed by the participant.

        Please note that you are unable to create a Service Booking for quotable items (including SDA, SIL and Assistive Technology)
      operationId: createservicebookings
      responses:
        '200':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/create_service_booking_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - POST
      parameters:
        - name: service_booking_request_data
          required: true
          in: body
          schema:
            $ref: '#/definitions/service_booking_request_data'
        - $ref: '#/parameters/authorization'
    get:
      responses:
        '200':
          description: 200 OK
          schema:
            $ref: '#/definitions/service_booking_list_response'
      tags: []
      produces:
        - application/json
      operationId: servicebookingslist
      parameters:
        - $ref: '#/parameters/participant'
        - $ref: '#/parameters/skip'
        - $ref: '#/parameters/top'
        - $ref: '#/parameters/orderby'
        - $ref: '#/parameters/sortorder'
        - $ref: '#/parameters/inlinecount'
      summary: Query list of Service Bookings
      description: This operation will retrieve all Service Bookings associated to a participant, you have a relationship with i.e. your organisation has one or more service booking(s) with. In order to get a successful response, ensure the participant's NDIS number is a valid 9 digit number starting with 43.
    parameters:
      - $ref: '#/parameters/authorization'
  /{service_booking_id}:
    get:
      operationId: servicebookingdetail
      summary: Retrieve a specific Service Booking
      description: Retrieves a specific service booking assigned to the provider
      responses:
        '200':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/service_booking_detail_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - GET
      parameters:
        - $ref: '#/parameters/participant'
    parameters:
      - name: service_booking_id
        type: integer
        required: true
        in: path
        format: int32
        x-example: 1011111
      - $ref: '#/parameters/authorization'
    patch:
      summary: Update service booking request
      description: Updates the current quantity and allocated amount of an existing service booking
      operationId: updateservicebookings
      responses:
        '204':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/update_service_booking_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - PATCH
      parameters:
        - name: update_service_booking_request_data
          required: true
          in: body
          schema:
            $ref: '#/definitions/update_service_booking_request_data'
        - $ref: '#/parameters/authorization'
    delete:
      summary: Delete service booking
      description: |-
        This operation allows the Digital Partners to delete a specific service booking. Service Bookings can be deleted only if 

        1. There is no payment created or saved against it
        2. There is no accrual against it   
        3. No payments have been made  

        Please note that

        1. Once a service booking is deleted, it will be removed from your list of service bookings permanently.
        2. You cannot delete a Service Booking initiated by NDIS staff.
      operationId: deleteservicebooking
      responses:
        '200':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/delete_service_booking_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - DELETE
      parameters:
        - $ref: '#/parameters/authorization'
      produces:
        - application/json
  /{service_booking_id}/extend-end-date:
    patch:
      summary: Extend End Date to a future date from the current end date for the service booking
      description: |-
        This operation allows the Digital Partners to extend the end date of an existing Service Booking. 

        Please note that, while you are able to extend the end date of an inactive Service Booking that is scheduled in the future, you cannot make changes to the end date of an inactive Service Booking whose end date has already passed.
      operationId: extendenddate
      responses:
        '200':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/extend_end_date_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - PATCH
      parameters:
        - name: extend_end_date_request_data
          required: true
          in: body
          schema:
            $ref: '#/definitions/extend_end_date_request_data'
    parameters:
      - $ref: '#/parameters/service_booking_id'
      - $ref: '#/parameters/authorization'
  /{service_booking_id}/reduce-end-date:
    patch:
      summary: Reduce End Date for the service booking
      description: |-
        This operation allows the Digital Partners to reduce the end date of an existing Service Booking. 

        Please note that, while you are able to reduce the end date of an inactive Service Booking that is scheduled in the future, you cannot make changes to the end date of an inactive Service Booking whose end date has already passed
      operationId: reduceenddate
      responses:
        '204':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/reduce_end_date_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - PATCH
      parameters:
        - name: reduce_end_date_request_data
          required: true
          in: body
          schema:
            $ref: '#/definitions/reduce_end_date_request_data'
    parameters:
      - $ref: '#/parameters/service_booking_id'
      - $ref: '#/parameters/authorization'
  /{service_booking_id}/update-status:
    patch:
      summary: Update Status for the service booking
      description: |-
        This operation allows the Digital Partners to update the status of a Service Booking, created or modified by the Participant. Note that only NEW Service Bookings in the status of 'Awaiting Review' (key = "APRO") or MODIFIED Service Bookings in the status of 'Review Change' (key = "APRC") can be accepted or rejected. 


        To approve a SB, the request body should be as below: 

        - { "booking_type": "ZSAG", "status": "APPR" }   

        To reject a SB, the request body should be as below. Rejection Reason is mandatory and can be retrieved using the NDIS Reference Data API - GET/{attribute_name} operation, replacing the attribute_name with "rejection_reason" . Rejection Notes is optional. 

        - { "booking_type": "ZSAG", "status": "REJT", "rejection_reason": "ZNFC", "rejection_notes": "Add some optional notes" }
      operationId: updatestatus
      responses:
        '200':
          description: 'Success: The request was successful'
          schema:
            $ref: '#/definitions/update_status_response'
        '400':
          description: 'Bad Request: A validation resulted in the request being rejected.'
          schema:
            $ref: '#/definitions/http_error'
        '401':
          description: 'Unauthorised: No authentication credentials provided or authentication has failed.'
          schema:
            $ref: '#/definitions/http_error'
        '404':
          description: The URI path or the requested record was not found.
          schema:
            $ref: '#/definitions/http_error'
        '500':
          description: 'Internal Server Error: An internal error has occurred and the server is unable to respond.'
          schema:
            $ref: '#/definitions/http_error'
      tags:
        - PATCH
      parameters:
        - name: update_status_request_data
          required: true
          in: body
          schema:
            $ref: '#/definitions/update_status_request_data'
    parameters:
      - $ref: '#/parameters/service_booking_id'
      - $ref: '#/parameters/authorization'
parameters:
  authorization:
    name: authorization
    type: string
    required: true
    in: header
    description: Bearer token
    x-example: valid Authorizaton Token
  participant:
    name: participant
    type: string
    required: true
    in: header
    description: The NDIS participant ID
    maxLength: 10
    x-example: 430111111
  skip:
    name: skip
    type: integer
    required: false
    in: header
    description: pagination field - No of rows to be skipped
    format: int32
    x-example: 1
  top:
    name: top
    type: integer
    required: false
    in: header
    description: pagination field - No of rows to be returned
    format: int32
    x-example: 1
  orderby:
    name: orderby
    type: string
    required: false
    in: header
    description: Pagination - sort by field
    x-example: field
  sortorder:
    name: sortorder
    type: string
    required: false
    in: header
    description: 'Pagination - sort order: valid values - asc/desc'
    x-example: asc
  inlinecount:
    name: inlinecount
    type: string
    required: false
    in: header
    description: allpages
    x-example: allpages
  service_booking_id:
    name: service_booking_id
    type: string
    required: true
    in: path
    description: service booking id
    x-example: 1011111
  Content-Type:
    name: Content-Type
    type: string
    required: true
    in: header
    description: Content Type eg:image/jpeg
definitions:
  update_service_booking_response:
    description: Response for updating a service booking
    properties:
      success:
        type: boolean
        example: true
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  extend_end_date_response:
    description: Response for extend end date
    properties:
      success:
        type: boolean
        example: true
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  reduce_end_date_response:
    description: Response for reduce end date
    properties:
      success:
        type: boolean
        example: true
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  update_status_response:
    description: Response for Update Status
    properties:
      success:
        type: boolean
        example: true
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  delete_service_booking_response:
    description: Response for delete service booking
    properties:
      success:
        type: boolean
        example: true
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  service_booking_detail_response:
    properties:
      success:
        type: boolean
        description: success status of call
        example: true
      result:
        $ref: '#/definitions/service_booking_detail'
        description: result object
    additionalProperties: false
  service_booking_details:
    type: array
    items:
      $ref: '#/definitions/service_booking_detail'
  service_booking_detail:
    properties:
      participant:
        type: integer
        description: participant Number
        maxLength: 10
        example: 4444444444
        format: int32
      participant_name:
        type: string
        description: participant Name
        maxLength: 80
        example: ABC
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 40
        example: Standard Booking
      service_booking_id:
        type: integer
        description: Service Booking Number
        maxLength: 10
        example: 55555556
        format: int32
      start_date:
        type: string
        description: Start Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      end_date:
        type: string
        description: End Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      revised_end_date:
        type: string
        description: Revised End Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      inkind_program:
        type: boolean
        description: In-Kind Program
        example: false
      status:
        type: string
        description: status
        maxLength: 30
        example: Approved
      virtual_status:
        type: string
        description: Virtualstatus
        maxLength: 30
        example: Active
      participant_plan_id:
        type: integer
        description: Participant Plan ID
        maxLength: 10
        example: 5555555
        format: int32
      provider_comments:
        type: string
        description: Comments
        example: test
      items:
        $ref: '#/definitions/service_booking_items'
        description: Service Boking Items Object
    additionalProperties: false
  service_booking_items:
    type: array
    items:
      $ref: '#/definitions/service_booking_item'
  service_booking_item:
    properties:
      product_category:
        type: string
        description: Participant Support Category
        example: ASSISTIVE_TECHNOLOGY
      product_category_item:
        type: string
        description: Support Category Item Number
        maxLength: 40
        example: '05_220627230_0122_1_2'
      product_category_item_desc:
        type: string
        description: Support Item name
        maxLength: 132
        example: Home Modifications - Bathroom Mod - Minimal Structural Work
      quantity:
        type: integer
        description: quantity
        example: 1
        format: int32
      allocated_amount:
        type: number
        description: Allocated Amount (unit price * quantity). P15 S2
        example: 10
        format: double
      remaining_amount:
        type: number
        description: Remaining Amount. P15 S2
        example: 0
        format: double
    additionalProperties: false
  extend_end_date_request_data:
    properties:
      booking_type:
        type: string
        description: Service Booking Type.
        example: ZSAG
        maxLength: 4
      end_date:
        type: string
        description: End Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
    additionalProperties: true
    required:
      - booking_type
      - end_date
  reduce_end_date_request_data:
    properties:
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 4
        example: ZSAG
      end_date:
        type: string
        description: End Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      cancellation_reason:
        type: string
        description: Cancellation Reason. The Reference Data - Attribute Name is cancellation_reasons
        maxLength: 10
        example: ZSRQ
      items:
        $ref: '#/definitions/reduce_end_date_items_request_data'
        description: Reduce End Date Items Request Object
    additionalProperties: true
    required:
      - booking_type
      - end_date
      - cancellation_reason
  reduce_end_date_items_request_data:
    type: array
    items:
      $ref: '#/definitions/reduce_end_date_item_request_data'
  reduce_end_date_item_request_data:
    properties:
      product_category_item:
        type: string
        description: Support Category Item Number
        maxLength: 40
        example: '05_220627230_0122_1_2'
      product_category:
        type: string
        description: Participant Support Category
        maxLength: 80
        example: ASSISTIVE_TECHNOLOGY
      item_type:
        type: string
        description: Item Type
        maxLength: 40
        example: ''
      accrualunit:
        type: number
        description: Accrual Unit. MaxLength P5 S0
        example: 1
        format: double
      accrualprice:
        type: number
        description: Accrual Price. MaxLength P15 S2
        example: 0.1
        format: double
    additionalProperties: true
    required:
      - product_category_item
      - product_category
      - accrualprice
  update_status_request_data:
    properties:
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 4
        example: ZSAG
      status:
        type: string
        description: Approve or Reject status - REJT or APPR
        example: REJT
      rejection_reason:
        type: string
        description: Rejection Reason (Mandatory ONLY when the status field is REJT). The Reference Data - Attribute Name is RejectionReason
        maxLength: 10
        example: ZNFC
      rejection_notes:
        type: string
        description: Rejection Notes (Optional ONLY when the status field is REJT)
        maxLength: 40
        example: For check rejection
    additionalProperties: true
    required:
      - booking_type
      - status
  update_service_booking_request_data:
    properties:
      product_category_item:
        type: string
        description: Support Category Item Number
        maxLength: 40
        example: '05_220627230_0122_1_2'
      product_category:
        type: string
        description: Participant Support Category
        maxLength: 80
        example: ASSISTIVE_TECHNOLOGY
      item_type:
        type: string
        description: Item Type
        example: ''
        maxLength: 40
      quantity:
        type: number
        description: quantity
        example: 1
        format: double
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 4
        example: ZSAG
      price:
        type: number
        description: Price
        example: 1.5
        format: double
    additionalProperties: true
    required:
      - product_category_item
      - product_category
      - booking_type
      - price
  service_booking_request_data:
    properties:
      participant:
        type: integer
        description: participant Number
        maxLength: 10
        example: 430000000
        format: int32
      participant_surname:
        type: string
        description: participant Surname
        maxLength: 80
        example: Test
      date_of_birth:
        type: string
        description: participant Date Of Birth
        example: YYYY-MM-DD
        pattern: ^\d{4}-\d{2}-\d{2}$
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 4
        example: ZSAG
      start_date:
        type: string
        description: Service Booking Start Date
        example: YYYY-MM-DD
        pattern: ^\d{4}-\d{2}-\d{2}$
      end_date:
        type: string
        description: Service Booking End Date
        example: YYYY-MM-DD
        pattern: ^\d{4}-\d{2}-\d{2}$
      participant_plan_id:
        type: integer
        description: Valid Active Plan Id
        maxLength: 10
        example: 1027034
        format: int32
      declaration:
        type: boolean
        description: Declare Booking has been discussed with and agreed by the participant
        example: true
      provider_comments:
        type: string
        description: Comments
        example: test
      items:
        $ref: '#/definitions/service_booking_items_request_data'
        description: Service Boking Items Request Object
    additionalProperties: true
    required:
      - participant
      - participant_surname
      - date_of_birth
      - booking_type
      - start_date
      - end_date
      - participant_plan_id
      - declaration
  service_booking_items_request_data:
    type: array
    items:
      $ref: '#/definitions/service_booking_item_request_data'
  service_booking_item_request_data:
    properties:
      product_category:
        type: string
        description: Participant Support Category
        maxLength: 80
        example: ASSISTIVE_TECHNOLOGY
      product_category_item:
        type: string
        description: Support Category Item Number
        maxLength: 40
        example: '05_220627230_0122_1_2'
      quantity:
        type: integer
        description: quantity
        example: 1
        format: int32
      per_unit_price:
        type: number
        description: Per Unit Price
        example: 0.1
        format: double
    additionalProperties: true
    required:
      - product_category
      - quantity
      - per_unit_price
  create_service_booking_response:
    properties:
      success:
        type: boolean
        example: true
      result:
        $ref: '#/definitions/create_service_booking_detail'
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  create_service_booking_details:
    type: array
    items:
      $ref: '#/definitions/create_service_booking_detail'
  create_service_booking_detail:
    properties:
      participant:
        type: integer
        description: participant Number
        maxLength: 10
        example: 4444444444
        format: int32
      participant_surname:
        type: string
        description: participant Name
        maxLength: 80
        example: ABC
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 40
        example: Standard Booking
      service_booking_id:
        type: integer
        description: Service Booking Number
        maxLength: 10
        example: 55555556
        format: int32
      start_date:
        type: string
        description: Start Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      end_date:
        type: string
        description: End Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      participant_plan_id:
        type: integer
        description: Participant Plan ID
        maxLength: 10
        example: 5555555
        format: int32
    additionalProperties: false
  service_booking_list_response:
    properties:
      success:
        type: boolean
        description: success status of call
        example: true
      result:
        $ref: '#/definitions/service_booking_list_items'
        description: result object
      errors:
        $ref: '#/definitions/errors'
    additionalProperties: false
    required:
      - success
  service_booking_list_items:
    type: array
    items:
      $ref: '#/definitions/service_booking_list_item'
  service_booking_list_item:
    properties:
      service_booking_id:
        type: integer
        description: Service Booking Number
        maxLength: 10
        example: 5555555
        format: int32
      booking_type:
        type: string
        description: Service Booking Type
        maxLength: 40
        example: Standard Service Booking
      participant:
        type: integer
        description: participant Number
        maxLength: 10
        example: 4444444444
        format: int32
      participant_name:
        type: string
        description: participant Name
        maxLength: 80
        example: ABC
      start_date:
        type: string
        description: Start Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      end_date:
        type: string
        description: End Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      submitted_date:
        type: string
        description: Submitted Date
        example: '2001-12-31'
        pattern: ^\d{4}-\d{2}-\d{2}$
      created_by:
        type: string
        description: Initiated By
        maxLength: 12
        example: '4444444444'
      status:
        type: string
        description: Service Booking status
        maxLength: 30
        example: Approved
      virtual_status:
        type: string
        description: Service Booking Virtualstatus
        maxLength: 30
        example: Active
      participant_plan_id:
        type: integer
        description: Participant Plan ID
        maxLength: 10
        example: 5555555
        format: int32
      provider_comments:
        type: string
        description: Comments
        example: test
    additionalProperties: false
  errors:
    description: A set of errors
    type: array
    items:
      type: string
      example: error
  http_error:
    description: A single HTTP response
    properties:
      http_code:
        type: string
        example: 400
        description: HTTP status code
      http_message:
        type: string
        example: Bad Request
        description: HTTP Message
      more_information:
        type: string
        example: One or more required API parameters are missing.
        description: Additional information
    additionalProperties: false
tags: []