Facilio Deliveries API

openapi: 3.2.0
info:
  title: Facilio REST Deliveries 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: Deliveries
  description: Deliveries track packages received on-site for employees, including carrier, tracking number, and delivery status.
paths:
  /deliveries:
    get:
      tags:
      - Deliveries
      summary: List deliveries
      operationId: listDeliveries
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: List of deliveries
          content:
            application/json:
              example:
                success: true
                data:
                - id: 200
                  employee:
                    id: 5
                    name: Jane Doe
                  carrier: FedEx
                  trackingNumber: '784561230'
                  deliveryArea:
                    id: 15
                  moduleState: Received
                pagination:
                  page: 1
                  pageSize: 50
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Deliveries
      summary: Create a delivery
      description: Creates a new delivery record. Requires `employee`, `receivedTime`, `deliveryArea`, and `carrier`.
      operationId: createDelivery
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/Delivery'
            example:
              data:
                employee: 5
                receivedTime: '2026-02-14T09:00:00Z'
                deliveryArea: 15
                carrier: UPS
                trackingNumber: 1Z999AA10123456784
      responses:
        '201':
          description: Delivery created
          content:
            application/json:
              example:
                success: true
                data:
                  id: 201
                  name: Jane Doe
                message: Record created
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deliveries/{id}:
    get:
      tags:
      - Deliveries
      summary: Get a delivery
      operationId: getDelivery
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: Delivery details
          content:
            application/json:
              example:
                success: true
                data:
                  id: 200
                  employee:
                    id: 5
                    name: Jane Doe
                  carrier: FedEx
                  trackingNumber: '784561230'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Deliveries
      summary: Update a delivery
      operationId: updateDelivery
      parameters:
      - $ref: '#/components/parameters/recordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/Delivery'
            example:
              data:
                deliveredTime: '2026-02-14T13:00:00Z'
      responses:
        '200':
          description: Delivery 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:
      - Deliveries
      summary: Delete a delivery
      operationId: deleteDelivery
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: Delivery deleted
          content:
            application/json:
              example:
                success: true
                message: Record deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /deliveries/metadata:
    get:
      tags:
      - Deliveries
      summary: Get delivery field schema
      description: Returns the field schema for the deliveries module, including all declared system fields and any org-specific custom fields with their data type, required/readOnly flags, and lookup targets.
      operationId: getDeliveryMetadata
      parameters:
      - $ref: '#/components/parameters/includeAllowedValues'
      responses:
        '200':
          description: Field schema retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleMetaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /deliveries/{id}/attachments:
    get:
      tags:
      - Deliveries
      summary: List delivery attachments
      description: Returns all file attachments for the specified delivery (e.g. package photo, signature).
      operationId: listDeliveryAttachments
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: List of attachments
          content:
            application/json:
              example:
                success: true
                data:
                - id: 301
                  fileName: package.jpg
                  fileSize: 204800
                  contentType: image/jpeg
                  createdTime: '2026-02-14T09:00:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Deliveries
      summary: Add delivery attachment
      description: Uploads a file attachment to the specified delivery. Use multipart/form-data.
      operationId: addDeliveryAttachment
      parameters:
      - $ref: '#/components/parameters/recordId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                attachment:
                  type: string
                  format: binary
                  description: The file to upload
      responses:
        '201':
          description: Attachment uploaded
          content:
            application/json:
              example:
                success: true
                data:
                - id: 302
                  fileName: package2.jpg
                  fileSize: 512000
                  contentType: image/jpeg
                message: Attachment(s) added successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deliveries/{id}/attachments/{attachmentId}:
    delete:
      tags:
      - Deliveries
      summary: Delete delivery attachment
      operationId: deleteDeliveryAttachment
      parameters:
      - $ref: '#/components/parameters/recordId'
      - $ref: '#/components/parameters/attachmentId'
      responses:
        '200':
          description: Attachment deleted
          content:
            application/json:
              example:
                success: true
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /deliveries/{id}/attachments/{attachmentId}/download:
    get:
      tags:
      - Deliveries
      summary: Download delivery attachment
      description: Downloads the file content of a specific attachment.
      operationId: downloadDeliveryAttachment
      parameters:
      - $ref: '#/components/parameters/recordId'
      - $ref: '#/components/parameters/attachmentId'
      responses:
        '200':
          description: File download
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /deliveries/{id}/comments:
    get:
      tags:
      - Deliveries
      summary: List delivery comments
      operationId: listDeliveryComments
      parameters:
      - $ref: '#/components/parameters/recordId'
      responses:
        '200':
          description: List of comments
          content:
            application/json:
              example:
                success: true
                data:
                - id: 401
                  body: Left at front desk
                  createdTime: '2026-02-14T09:05:00Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      tags:
      - Deliveries
      summary: Add delivery comment
      operationId: addDeliveryComment
      parameters:
      - $ref: '#/components/parameters/recordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/DeliveryComment'
            example:
              data:
                body: Recipient notified by email.
      responses:
        '201':
          description: Comment added
          content:
            application/json:
              example:
                success: true
                data:
                  id: 402
                  body: Recipient notified by email.
                message: Comment added successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /deliveries/{id}/comments/{commentId}:
    patch:
      tags:
      - Deliveries
      summary: Update delivery comment
      operationId: updateDeliveryComment
      parameters:
      - $ref: '#/components/parameters/recordId'
      - $ref: '#/components/parameters/commentId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - body
                  properties:
                    body:
                      type: string
            example:
              data:
                body: Recipient picked up in person.
      responses:
        '200':
          description: Comment updated
          content:
            application/json:
              example:
                success: true
                message: Comment updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      tags:
      - Deliveries
      summary: Delete delivery comment
      operationId: deleteDeliveryComment
      parameters:
      - $ref: '#/components/parameters/recordId'
      - $ref: '#/components/parameters/commentId'
      responses:
        '200':
          description: Comment deleted
          content:
            application/json:
              example:
                success: true
                message: Comment deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    ModuleMetaResponse:
      type: object
      description: Response body for GET /{moduleName}/metadata.
      properties:
        success:
          type: boolean
        data:
          type: object
          properties:
            module:
              $ref: '#/components/schemas/FacilioModule'
            fields:
              type: array
              description: 'Ordered list of fields for the module.

                Standard Facilio modules return built-in fields first, followed by any fields your organization added.

                Custom modules return all fields.

                '
              items:
                $ref: '#/components/schemas/FacilioField'
    User:
      type: object
      description: 'Expanded object for lookups to the `users` module.

        On list API, user lookups return `{id}` only unless `?expand=` includes that field.

        When expanded (single-record GET, create/update responses, or list with `expand`): fixed set `id`, `name`, `email`, `phone` (see **Lookup fields in responses**).

        '
      properties:
        id:
          type: integer
          format: int64
          description: User ID
        name:
          type: string
          description: User's full name
        email:
          type: string
          description: User's email address
        phone:
          type: string
          description: Phone number when present
    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
    FacilioModule:
      type: object
      description: A single entry in the module catalogue returned by GET /modules.
      properties:
        name:
          type: string
          description: Module name used in all API paths (e.g. `workorder`, `custom_employees`)
        displayName:
          type: string
          description: Human-readable module label (e.g. `Work Orders`, `Employees`)
        description:
          type: string
          description: Module description as configured in Facilio Setup. Omitted when blank.
        isCustom:
          type: boolean
          description: '`true` for modules created by your organization; `false` for standard Facilio modules'
    DeliveryComment:
      type: object
      description: Delivery comment/note.
      required:
      - body
      properties:
        id:
          type: integer
          readOnly: true
          description: Comment ID
        body:
          type: string
          description: Comment text content (required on create)
        createdTime:
          type: string
          format: date-time
          readOnly: true
          description: Creation timestamp
        createdBy:
          readOnly: true
          description: User who posted the comment
          allOf:
          - $ref: '#/components/schemas/User'
    Delivery:
      type: object
      description: A package received on-site for an employee.
      required:
      - employee
      - receivedTime
      - deliveryArea
      - carrier
      properties:
        id:
          type: integer
          readOnly: true
          description: Unique record ID
        name:
          type: string
          readOnly: true
          description: Auto-filled from the recipient employee's name
        employee:
          type: integer
          description: Recipient employee ID (required on create)
        receivedTime:
          type: string
          format: date-time
          description: When the delivery was received (required on create, sortable)
        deliveredTime:
          type: string
          format: date-time
          description: When the delivery was handed off to the recipient
        avatar:
          type: string
          description: Package photo — see the file field API
        signature:
          type: string
          description: Recipient signature — see the file field API
        trackingNumber:
          type: string
          description: Carrier tracking number
        deliveryArea:
          type: integer
          description: Delivery area ID (required on create)
        carrier:
          type: string
          description: Carrier name (required on create). Use `GET /picklist/deliveries/carrier` for valid values (e.g. UPS, FedEx, US Postal Service, Amazon, DHL).
        moduleState:
          type: string
          readOnly: true
          description: Status. Use `GET /picklist/deliveries/moduleState` for valid values.
        approvalStatus:
          type: string
          readOnly: true
          description: Approval sub-status
        sysCreatedTime:
          type: string
          format: date-time
          readOnly: true
          description: Creation timestamp (sortable)
        sysModifiedTime:
          type: string
          format: date-time
          readOnly: true
          description: Last modified (sortable)
    FacilioField:
      type: object
      description: Schema descriptor for a single field within a module.
      properties:
        name:
          type: string
          description: Field name used in API requests and responses (e.g. `subject`, `po_reference_workorder`)
        displayName:
          type: string
          description: Human-readable field label
        dataType:
          type: string
          description: 'Field data type. Common values:

            `STRING`, `NUMBER`, `DECIMAL`, `BOOLEAN`,

            `DATE`, `DATE_TIME`,

            `BIG_STRING` (large text, excluded from list responses),

            `LOOKUP` (reference to another record — see `lookupModuleName`),

            `MULTI_LOOKUP` (multi-reference — see `lookupModuleName`),

            `ENUM`, `SYSTEM_ENUM`, `STRING_SYSTEM_ENUM` (picklist types)

            '
          example: STRING
        required:
          type: boolean
          description: '`true` if this field must be provided on record creation'
        readOnly:
          type: boolean
          description: '`true` if this field cannot be set or modified via the API (e.g. auto-generated system fields)'
        isCustom:
          type: boolean
          description: '`true` for fields added by your organization; `false` for standard built-in fields'
        sortable:
          type: boolean
          description: '`true` if this field can be used as a `sortBy` value on the list API'
        lookupModuleName:
          type: string
          description: Present only on `LOOKUP` and `MULTI_LOOKUP` fields. The name of the target module (e.g. `site`, `users`, `ticketstatus`).
        max_length:
          type: integer
          description: 'Maximum number of characters accepted by the V5 write API for text-style fields.

            Present only when the field''s `dataType` is one of:

            `STRING` (255), `LARGE_TEXT` (2000), `BIG_STRING` (32000).

            Omitted for all other data types.

            '
          example: 255
        allowed_values:
          type: array
          description: 'List of acceptable write values for picklist-capable fields. Present **only when the request includes `?includeAllowedValues=true`** AND the field is one of:

            `ENUM`, `SYSTEM_ENUM`, `MULTI_ENUM`, `STRING_SYSTEM_ENUM`, or a `LOOKUP` targeting a system picklist module (e.g. `ticketstatus`, `ticketpriority`, `ticketcategory`, `tickettype`).

            Each entry uses `{label, value}`; the `value` is the canonical form accepted by create/update payloads.

            '
          items:
            type: object
            properties:
              label:
                type: string
                description: Display label as shown in the UI
              value:
                type: string
                description: Canonical value accepted by create/update for this field and filtering
  parameters:
    select:
      name: select
      in: query
      description: Comma-separated field names to include in the response
      schema:
        type: string
    search:
      name: search
      in: query
      description: Free-text search on the primary field (subject, name, etc.)
      schema:
        type: string
    page:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        default: 1
    pageSize:
      name: pageSize
      in: query
      description: Records per page (max 200)
      schema:
        type: integer
        default: 50
        maximum: 200
    recordId:
      name: id
      in: path
      required: true
      description: Record ID
      schema:
        type: integer
        format: int64
    includeAllowedValues:
      name: includeAllowedValues
      in: query
      description: 'When `true`, the metadata response adds `allowed_values` ([{label, value}]) on every picklist-capable field — `ENUM`, `SYSTEM_ENUM`, `MULTI_ENUM`, `STRING_SYSTEM_ENUM`, and `LOOKUP` fields targeting system picklist modules (status, priority, category, type, ...).

        Default `false` keeps the original metadata payload (no enrichment, no extra DB calls).

        Use this to discover acceptable write values without round-tripping `GET /picklist/{moduleName}/{fieldName}` for every picklist field.

        '
      schema:
        type: boolean
        default: false
    attachmentId:
      name: attachmentId
      in: path
      required: true
      description: Attachment ID
      schema:
        type: integer
        format: int64
    commentId:
      name: commentId
      in: path
      required: true
      description: Comment ID
      schema:
        type: integer
        format: int64
    count:
      name: count
      in: query
      description: Include total record count in response
      schema:
        type: boolean
        default: false
  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'
    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
    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
  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)