Facilio Facility Special Availability API

openapi: 3.2.0
info:
  title: Facilio REST Facility Special Availability API
  version: 5.0.0
  description: 'The Facilio REST API gives you programmatic access to Facilio''s Connected CMMS — the unified platform for managing property operations at portfolio scale. Build integrations that connect Facilio with your ERP, accounting systems, BMS, IoT platforms, and other business tools. Automate work order creation from external triggers, synchronize asset data across systems, push tenant and vendor records from your CRM, or pull maintenance data into your reporting dashboards. **What you can do with this API:**

    - **Work Orders & Service Requests** — Create, assign, track, and close maintenance tasks programmatically

    - **Assets** — Manage your equipment registry, track asset lifecycle, and sync with external asset management systems

    - **Portfolio (Sites, Buildings, Floors, Spaces)** — Maintain your facility hierarchy and space data

    - **People (Tenants, Vendors, Clients)** — Synchronize contacts and stakeholder records

    - **Inventory (Item Types, Tool Types, Items & Tools, Services, Storerooms)** — Master data, per-storeroom item/tool balances (read), per-bin quantities by item or tool record, quantity adjustments, and warehouse locations

    - **Procurement (Quotes, Purchase Requests, Purchase Orders, Receivable receiving, Invoices)** — Procurement with line items; receive against a PO via receivable APIs

    - **Credit Notes (Vendor Credits, Client Credits)** — Manage credit notes for refunds and transaction adjustments with line items

    - **Inventory Requests** — Track material requisitions from work orders to storerooms

    - **Custom Modules** — Manage your organization''s custom modules — record types you define for the data and workflows that are specific to your business

    - **Schema Discovery** — List all accessible modules and inspect field schemas (name, type, required, readOnly, lookup target) via `GET /modules` and `GET /{moduleName}/metadata`

    - **Attachments & Comments** — Attach documents, photos, and notes to work orders and service requests

    - **Picklists** — Discover available values for status, priority, category, and other configurable fields


    The API follows REST conventions with JSON request/response bodies, standard HTTP methods (GET, POST, PATCH, DELETE), and consistent error handling across all endpoints. ## Base URL


    ```

    https://{region}.facilioapis.com/{app_name}/api/v5

    ```


    | Variable | Description | Values |

    |----------|-------------|--------|

    | `region` | Your deployment region | `us`, `au`, `ae`, `uk`, `us-azure`, `sa` |

    | `app_name` | `maintenance` for API Key auth, `developer` for OAuth2 auth | `maintenance`, `developer` |


    ## Authentication


    All API requests must be authenticated using one of the following methods:


    ### API Key (Personal Access Token)

    Generate an API key from your Facilio account settings and pass it in the `x-api-key` header. The key inherits the permissions of the user who created it. ```

    x-api-key: your-api-key-here

    ```


    ### OAuth2

    For developer app integrations. Supports **authorization_code** and **password** grant types. | Endpoint | URL |

    |----------|-----|

    | Authorize | `https://{region}.facilioapis.com/identity/oauth2/authorize` |

    | Token | `https://{region}.facilioapis.com/identity/oauth2/token` |

    | Refresh | `https://{region}.facilioapis.com/identity/oauth2/token` (with `grant_type=refresh_token`) |

    | Revoke | `https://{region}.facilioapis.com/identity/oauth2/revoke` |


    Pass the access token as:

    ```

    Authorization: Bearer oauth2

    ```


    ---


    ## List Operations


    All list endpoints (`GET /{module}`) support these query parameters:


    | Parameter | Type | Default | Description |

    |-----------|------|---------|-------------|

    | `page` | integer | 1 | Page number (1-based) |

    | `pageSize` | integer | 50 | Number of records per page. Maximum is 200. |

    | `select` | string | — | Comma-separated field names to include in the response. If omitted, module default fields are returned. |

    | `expand` | string | — | Comma-separated lookup field names to expand with full details (max 5).'
  contact:
    name: Facilio Support
    url: https://facilio.com
  license:
    name: Proprietary
servers:
- url: https://{region}.facilioapis.com/{app_name}/api/v5
  variables:
    region:
      description: Regional deployment
      default: us
      enum:
      - us
      - au
      - ae
      - uk
      - us-azure
      - sa
    app_name:
      description: '''maintenance'' for API Key, ''developer'' for OAuth2'
      default: maintenance
      enum:
      - maintenance
      - developer
security:
- apiKey: []
- oauth2: []
tags:
- name: Facility Special Availability
  description: Date-range overrides on a facility's normal availability — an extra window or a blackout, optionally at a special cost.
paths:
  /facilitySpecialAvailability:
    get:
      tags:
      - Facility Special Availability
      summary: List facility special availability overrides
      operationId: listFacilitySpecialAvailability
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: List of special availability overrides
          content:
            application/json:
              example:
                success: true
                data:
                - id: 1200
                  facility:
                    id: 700
                  startDate: '2026-12-25T00:00:00Z'
                  endDate: '2026-12-25T00:00:00Z'
                  specialType: Special Unavailability
                  remarks: Closed for holiday
                pagination:
                  page: 1
                  pageSize: 50
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Facility Special Availability
      summary: Create a facility special availability override
      description: Requires `facility`, `startDate`, `endDate`, `actualStartTime`/`actualEndTime` (seconds since midnight), `cost`, and `remarks`.
      operationId: createFacilitySpecialAvailability
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/FacilitySpecialAvailability'
            example:
              data:
                facility: 700
                startDate: '2026-12-25T00:00:00Z'
                endDate: '2026-12-25T00:00:00Z'
                actualStartTime: 0
                actualEndTime: 0
                cost: 0
                specialType: Special Unavailability
                remarks: Closed for holiday
      responses:
        '201':
          description: Special availability override created
          content:
            application/json:
              example:
                success: true
                data:
                  id: 1201
                message: Record created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /facilitySpecialAvailability/{id}:
    get:
      tags:
      - Facility Special Availability
      summary: Get a facility special availability override
      operationId: getFacilitySpecialAvailability
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: Special availability override details
          content:
            application/json:
              example:
                success: true
                data:
                  id: 1200
                  specialType: Special Unavailability
                  remarks: Closed for holiday
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Facility Special Availability
      summary: Update a facility special availability override
      operationId: updateFacilitySpecialAvailability
      parameters:
      - $ref: '#/components/parameters/recordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/FacilitySpecialAvailability'
            example:
              data:
                remarks: Closed for renovation
      responses:
        '200':
          description: Special availability override updated
          content:
            application/json:
              example:
                success: true
                message: Record updated
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Facility Special Availability
      summary: Delete a facility special availability override
      operationId: deleteFacilitySpecialAvailability
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: Special availability override deleted
          content:
            application/json:
              example:
                success: true
                message: Record deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    recordId:
      name: id
      in: path
      required: true
      description: Record ID
      schema:
        type: integer
        format: int64
    select:
      name: select
      in: query
      description: Comma-separated field names to include in the response
      schema:
        type: string
    page:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        default: 1
    count:
      name: count
      in: query
      description: Include total record count in response
      schema:
        type: boolean
        default: false
    pageSize:
      name: pageSize
      in: query
      description: Records per page (max 200)
      schema:
        type: integer
        default: 50
        maximum: 200
  responses:
    BadRequest:
      description: Validation error — missing required fields, invalid field values, or malformed request body
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: VALIDATION_ERROR
              message: 'Required field(s) missing: name'
    Unauthorized:
      description: Missing or invalid authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: UNAUTHORIZED
              message: Missing or invalid authentication credentials
    NotFound:
      description: Record or module not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error:
              code: RECORD_NOT_FOUND
              message: Record with the given ID was not found
  schemas:
    FacilitySpecialAvailability:
      type: object
      description: A date-range override on a facility's normal availability — an extra window or a blackout.
      required:
      - facility
      - startDate
      - endDate
      - actualStartTime
      - actualEndTime
      - cost
      - remarks
      properties:
        id:
          type: integer
          readOnly: true
          description: Unique record ID
        facility:
          type: integer
          description: Facility this override applies to (required on create)
        startDate:
          type: string
          format: date-time
          description: Override start date (required on create, sortable)
        endDate:
          type: string
          format: date-time
          description: Override end date (required on create)
        actualStartTime:
          type: integer
          description: Window start, seconds since midnight (required on create)
        actualEndTime:
          type: integer
          description: Window end, seconds since midnight (required on create)
        cost:
          type: number
          description: Cost for this override, if different from normal (required on create)
        specialType:
          type: string
          description: Special Availability (extra window) or Special Unavailability (blackout)
        remarks:
          type: string
          description: Reason/notes for this override (required on create)
        cancelOnCostChange:
          type: boolean
          default: false
          description: Whether existing bookings should be cancelled if this override changes their cost
    Error:
      type: object
      description: Error response
      properties:
        success:
          type: boolean
          example: false
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code
            message:
              type: string
              description: Human-readable error message
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: Personal access token
    oauth2:
      type: oauth2
      description: Supports authorization_code and password grant types
      flows:
        authorizationCode:
          authorizationUrl: https://us.facilioapis.com/identity/oauth2/authorize
          tokenUrl: https://us.facilioapis.com/identity/oauth2/token
          refreshUrl: https://us.facilioapis.com/identity/oauth2/token
          scopes: {}
        password:
          tokenUrl: https://us.facilioapis.com/identity/oauth2/token
          refreshUrl: https://us.facilioapis.com/identity/oauth2/token
          scopes: {}
x-provenance:
  method: harvested
  publisher: Facilio
  source: https://static.facilio.com/developers/api/v5/openapi.yaml
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)