Facilio Receivables API

openapi: 3.2.0
info:
  title: Facilio REST Receivables 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.
  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: Receivables
  description: One receiving record per purchase order; list, read, and drive receipts through action endpoints.
paths:
  /receivable:
    get:
      tags:
      - Receivables
      summary: List receivables
      description: 'Returns receivable records. Filter by purchase order with **`?poId={purchaseOrderId}`** (lookup id).

        Standard list parameters (`page`, `pageSize`, `select`, etc.) apply.'
      operationId: listReceivables
      parameters:
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      - $ref: '#/components/parameters/search'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/changed'
      - name: poId
        in: query
        description: Purchase order id — returns receivable(s) for that PO (typically one row).
        schema:
          type: integer
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - id
          - localId
          - status
          - requiredTime
          - sysCreatedTime
          - sysModifiedTime
      - name: sortOrder
        in: query
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
      responses:
        '200':
          description: List of receivables
          content:
            application/json:
              example:
                success: true
                data:
                - id: 12
                  localId: 12
                  status: Partially Received
                  poId:
                    id: 12
                  vendor:
                    id: 1
                  storeRoom:
                    id: 1
                  sysCreatedTime: '2026-04-13T12:39:57Z'
                pagination:
                  page: 1
                  pageSize: 50
        '401':
          $ref: '#/components/responses/Unauthorized'
  /receivable/{id}:
    get:
      tags:
      - Receivables
      summary: Get a receivable
      description: Single receivable with linked PO summary fields. Child **`receipts`** array lists receipt rows for this receivable.
      operationId: getReceivable
      parameters:
      - $ref: '#/components/parameters/recordId'
      - $ref: '#/components/parameters/select'
      - $ref: '#/components/parameters/expand'
      responses:
        '200':
          description: Receivable with receipts
          content:
            application/json:
              example:
                success: true
                data:
                  id: 12
                  localId: 12
                  status: Partially Received
                  poId:
                    id: 12
                    name: PO-001
                    storeRoom:
                      id: 1
                  vendor:
                    id: 1
                  storeRoom:
                    id: 1
                  receipts:
                  - id: 4
                    receivableId: 12
                    lineItem:
                      id: 69
                    quantity: 2.0
                    status: Received
                    receiptTime: '2026-04-13T12:40:25Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /receivable/{id}/addreceipt:
    post:
      tags:
      - Receivables
      summary: Add a receipt line
      description: Record how much was received against a purchase order line for this receivable. Send the line item reference and quantity in the body (see examples).
      operationId: receivableAddReceipt
      parameters:
      - $ref: '#/components/parameters/recordId'
      - name: executeWorkflows
        in: query
        schema:
          type: boolean
          default: true
        description: When false, configured automations are not run for this request (default true).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  $ref: '#/components/schemas/Receipt'
            example:
              data:
                lineItem: 75
                quantity: 1
      responses:
        '201':
          description: Receipt created
          content:
            application/json:
              example:
                success: true
                message: Receipt created
                data:
                  id: 7
                  receivableId: 12
                  lineItem:
                    id: 75
                  quantity: 1.0
                  status: Received
                  receiptTime: '2026-04-13T15:53:33Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /receivable/{id}/stock:
    post:
      tags:
      - Receivables
      summary: Stock received PO lines into the storeroom
      description: Update storeroom inventory for item and tool lines that have already been received on this receivable. Send the rows in the request body (see examples). Requires update access on receivables.
      operationId: receivableStock
      parameters:
      - $ref: '#/components/parameters/recordId'
      - name: executeWorkflows
        in: query
        schema:
          type: boolean
          default: true
        description: When false, configured automations are not run for this request (default true).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - data
              properties:
                data:
                  type: object
                  description: Array of stocking rows in `lineItems`, or the same array under `lineItemsStockQuantity`. At least one must be present and non-empty.
                  properties:
                    lineItems:
                      type: array
                      items:
                        $ref: '#/components/schemas/POLineItemStock'
                    lineItemsStockQuantity:
                      type: array
                      items:
                        $ref: '#/components/schemas/POLineItemStock'
            example:
              data:
                lineItems:
                - lineItem: 77
                  quantity: 1
                  receipt: 7
                  bin: Receiving-Aisle-1
      responses:
        '200':
          description: Stock posted
          content:
            application/json:
              example:
                success: true
                data:
                  success: true
                  purchaseOrderId: 16
                  receivableId: 16
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /receivable/metadata:
    get:
      tags:
      - Receivables
      summary: Get receivable field schema
      description: Field schema for the receivable module (system + custom fields).
      operationId: getReceivableMetadata
      parameters:
      - $ref: '#/components/parameters/includeAllowedValues'
      responses:
        '200':
          description: Field schema
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModuleMetaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    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
    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'
    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
    Receipt:
      type: object
      description: 'Receipt line for `POST /receivable/{id}/addreceipt` (sent inside request `data`).

        Responses include read-only fields such as `id`, `receivableId`, `status`, and `receiptTime`.

        '
      required:
      - lineItem
      - quantity
      properties:
        lineItem:
          description: Purchase order line item id — pass the number directly (object with `id` is also accepted).
        quantity:
          type: number
          format: double
          minimum: 0
        bin:
          description: Optional bin id or name object for receipt routing
        remarks:
          type: string
        noOfSerialNumbers:
          type: integer
          minimum: 0
          description: Optional. Use only when the PO line requires serial capture; omit for standard lines.
    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'
    POLineItemStock:
      type: object
      description: One line in `POST /receivable/{id}/stock` (`lineItems` or `lineItemsStockQuantity`). Pass line, receipt, and lot as numeric ids where possible; use a string or id/name object for bin.
      properties:
        lineItem:
          description: Purchase order line id — numeric, or object with `id`.
        quantity:
          type: number
          format: double
        receipt:
          description: Receipt record id — numeric, or object with `id`.
        bin:
          description: Storeroom bin — bin name as a string, or object with `id` and/or `name`.
        lot:
          description: Lot id when the line is lot-tracked — numeric, or object with `id`.
        stockedBy:
          type: object
          description: Optional user reference, e.g. object with `id`.
  parameters:
    page:
      name: page
      in: query
      description: Page number (1-based)
      schema:
        type: integer
        default: 1
    recordId:
      name: id
      in: path
      required: true
      description: Record ID
      schema:
        type: integer
        format: int64
    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
    changed:
      name: changed
      in: query
      description: 'Delta sync: returns records created/modified after this UTC timestamp'
      schema:
        type: string
        format: date-time
    expand:
      name: expand
      in: query
      description: 'Comma-separated lookup field names to expand on **list** endpoints (max 5).

        Expanded objects follow the same rules as single-record GET (see **Lookup fields in responses** in the API overview).

        '
      schema:
        type: string
    search:
      name: search
      in: query
      description: Free-text search on the primary field (subject, name, etc.)
      schema:
        type: string
    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
    select:
      name: select
      in: query
      description: Comma-separated field names to include in the response
      schema:
        type: string
  responses:
    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
    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
  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: {}