{
  "openapi": "3.0.3",
  "info": {
    "title": "AlayaCare Residential — Finance journals API",
    "description": "HTTP contract for journal operations under `/Journals/Journal` relative to the Residential API base (commonly with an `/api` prefix). Authenticate like your other Residential integrations; caller must have finance journal read, write, or delete access as required per operation. See journals_api_documentation.md for narrative guidance. Enumeration names and numeric values are documented on each tenant's API Help pages, e.g. `{apiRoot}/Help/ResourceModel?modelName=JournalRecType`. Example Help index: https://residential.alayacare.com.au/api/Help",
    "version": "1.0.0"
  },
  "externalDocs": {
    "description": "Example Residential API Help index (replace host with your environment).",
    "url": "https://residential.alayacare.com.au/api/Help"
  },
  "servers": [
    {
      "url": "https://your-residential-host.example.com/api",
      "description": "Replace with the base URL provided for your integration (include /api or equivalent prefix if used in your tenant)."
    }
  ],
  "tags": [
    {
      "name": "Journal",
      "description": "Create, search, update, delete, post, and reverse finance journals."
    }
  ],
  "paths": {
    "/Journals/Journal": {
      "get": {
        "tags": ["Journal"],
        "summary": "List journals (paged)",
        "description": "Returns a wrapper object: total matching count, `data` array of journals, optional `lastId` for paging.",
        "operationId": "getJournalsPaged",
        "parameters": [
          { "$ref": "#/components/parameters/IncludeActive" },
          { "$ref": "#/components/parameters/IncludeInactive" },
          { "$ref": "#/components/parameters/IncludeDeleted" },
          { "$ref": "#/components/parameters/IncludeError" },
          { "$ref": "#/components/parameters/IncludeItems" },
          { "$ref": "#/components/parameters/Match" },
          { "$ref": "#/components/parameters/Journals" },
          { "$ref": "#/components/parameters/BusinessUnits" },
          { "$ref": "#/components/parameters/BusinessUnitNames" },
          { "$ref": "#/components/parameters/JournalTypes" },
          { "$ref": "#/components/parameters/JournalTypeNames" },
          { "name": "journalNumber", "in": "query", "schema": { "type": "integer" } },
          { "$ref": "#/components/parameters/JournalType" },
          { "$ref": "#/components/parameters/JournalTypeParents" },
          { "$ref": "#/components/parameters/JournalStatuses" },
          { "name": "journalStatusDateUtcMin", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "journalStatusDateUtcMax", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "journalDescription", "in": "query", "schema": { "type": "string" } },
          { "name": "createdDateUtcMin", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "createdDateUtcMax", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "lastUpdatedDateUtcMin", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "lastUpdatedDateUtcMax", "in": "query", "schema": { "type": "string", "format": "date-time" } },
          { "name": "skip", "in": "query", "schema": { "type": "integer", "minimum": 0 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 0 } }
        ],
        "responses": {
          "200": {
            "description": "Paged journal list.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/PagedJournalList" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Journal"],
        "summary": "Create journal",
        "operationId": "createJournal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Journal" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "headers": {
              "Location": { "schema": { "type": "string" } }
            }
          },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/Journals/Journal/{validateOnly}": {
      "post": {
        "tags": ["Journal"],
        "summary": "Create journal (validate-only path segment)",
        "operationId": "createJournalValidatePath",
        "parameters": [
          {
            "name": "validateOnly",
            "in": "path",
            "required": true,
            "schema": { "type": "boolean" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Journal" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created when validateOnly is false.",
            "headers": {
              "Location": { "schema": { "type": "string" } }
            }
          },
          "200": { "description": "Validation succeeded when validateOnly is true." },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/Journals/Journal/Initialize": {
      "get": {
        "tags": ["Journal"],
        "summary": "Initialize empty journal",
        "operationId": "initializeJournal",
        "responses": {
          "200": {
            "description": "Empty journal template for editing.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Journal" }
              }
            }
          }
        }
      }
    },
    "/Journals/Journal/{journalID}": {
      "get": {
        "tags": ["Journal"],
        "summary": "Get journal by id",
        "operationId": "getJournalById",
        "parameters": [{ "$ref": "#/components/parameters/JournalIdPath" }],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Journal" }
              }
            },
            "description": "OK"
          },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "put": {
        "tags": ["Journal"],
        "summary": "Update journal",
        "operationId": "updateJournal",
        "parameters": [{ "$ref": "#/components/parameters/JournalIdPath" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Journal" }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated." },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      },
      "delete": {
        "tags": ["Journal"],
        "summary": "Delete journal (soft)",
        "operationId": "deleteJournal",
        "parameters": [{ "$ref": "#/components/parameters/JournalIdPath" }],
        "responses": {
          "200": { "description": "Deleted." },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/Journals/Journal/{journalID}/{validateOnly}": {
      "put": {
        "tags": ["Journal"],
        "summary": "Update journal (validate-only path segment)",
        "operationId": "updateJournalValidatePath",
        "parameters": [
          { "$ref": "#/components/parameters/JournalIdPath" },
          {
            "name": "validateOnly",
            "in": "path",
            "required": true,
            "schema": { "type": "boolean" }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Journal" }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated or validation OK." },
          "400": { "$ref": "#/components/responses/BadRequest" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/Journals/Journal/{journalID}/{purge}": {
      "delete": {
        "tags": ["Journal"],
        "summary": "Delete or purge journal",
        "operationId": "deleteJournalPurge",
        "parameters": [
          { "$ref": "#/components/parameters/JournalIdPath" },
          {
            "name": "purge",
            "in": "path",
            "required": true,
            "schema": { "type": "boolean" }
          }
        ],
        "responses": {
          "200": { "description": "Deleted or purged." },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/Journals/Journal/{journalID}/PaymentStatus": {
      "get": {
        "tags": ["Journal"],
        "summary": "Get journal payment status",
        "operationId": "getJournalPaymentStatus",
        "parameters": [{ "$ref": "#/components/parameters/JournalIdPath" }],
        "responses": {
          "200": {
            "description": "PaymentStatus as integer or null. Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=PaymentStatus",
            "content": {
              "application/json": {
                "schema": {
                  "type": "integer",
                  "nullable": true,
                  "enum": [1, 2, 3],
                  "description": "PaymentStatus: 1=Draft, 2=Posted, 3=Processing. See Help ResourceModel PaymentStatus."
                }
              }
            }
          }
        }
      }
    },
    "/Journals/Journal/{journalID}/Post": {
      "put": {
        "tags": ["Journal"],
        "summary": "Post journal",
        "operationId": "postJournal",
        "parameters": [{ "$ref": "#/components/parameters/JournalIdPath" }],
        "responses": {
          "200": { "description": "Posted." },
          "400": { "$ref": "#/components/responses/BadRequest" }
        }
      }
    },
    "/Journals/Journal/Reverse": {
      "post": {
        "tags": ["Journal"],
        "summary": "Reverse journal",
        "operationId": "reverseJournal",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/JournalReversalRequest" }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Reversal journal created.",
            "headers": {
              "Location": { "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Journal" }
              }
            }
          }
        }
      }
    },
    "/Journals/Journal/ReverseDraftSettlement/{parentJournalItemId}/{account}": {
      "post": {
        "tags": ["Journal"],
        "summary": "Reverse draft settlement",
        "operationId": "reverseDraftSettlement",
        "parameters": [
          {
            "name": "parentJournalItemId",
            "in": "path",
            "required": true,
            "schema": { "type": "integer", "minimum": 1 }
          },
          {
            "name": "account",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": { "description": "OK." },
          "400": { "description": "Invalid parentJournalItemId or account." }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "JournalIdPath": {
        "name": "journalID",
        "in": "path",
        "required": true,
        "schema": { "type": "integer", "minimum": 1 }
      },
      "IncludeActive": {
        "name": "includeActive",
        "in": "query",
        "schema": { "type": "boolean" }
      },
      "IncludeInactive": {
        "name": "includeInactive",
        "in": "query",
        "schema": { "type": "boolean" }
      },
      "IncludeDeleted": {
        "name": "includeDeleted",
        "in": "query",
        "schema": { "type": "boolean" }
      },
      "IncludeError": {
        "name": "includeError",
        "in": "query",
        "schema": { "type": "boolean" }
      },
      "IncludeItems": {
        "name": "includeItems",
        "in": "query",
        "schema": { "type": "boolean" }
      },
      "Match": {
        "name": "match",
        "in": "query",
        "description": "String match for applicable text filters. Values 1–4 map to Full, PartialStarting, PartialAnywhere, Like. Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=MatchCriteriaStringType",
        "schema": {
          "type": "string",
          "enum": ["Full", "PartialStarting", "PartialAnywhere", "Like"]
        }
      },
      "Journals": {
        "name": "journals",
        "in": "query",
        "schema": { "type": "array", "items": { "type": "integer" } },
        "style": "form",
        "explode": true
      },
      "BusinessUnits": {
        "name": "businessUnits",
        "in": "query",
        "schema": { "type": "array", "items": { "type": "integer" } },
        "style": "form",
        "explode": true
      },
      "BusinessUnitNames": {
        "name": "businessUnitNames",
        "in": "query",
        "schema": { "type": "array", "items": { "type": "string" } },
        "style": "form",
        "explode": true
      },
      "JournalTypes": {
        "name": "journalTypes",
        "in": "query",
        "schema": { "type": "array", "items": { "type": "integer" } },
        "style": "form",
        "explode": true
      },
      "JournalTypeNames": {
        "name": "journalTypeNames",
        "in": "query",
        "schema": { "type": "array", "items": { "type": "string" } },
        "style": "form",
        "explode": true
      },
      "JournalType": {
        "name": "journalType",
        "in": "query",
        "description": "JournalRecType: Manual=1, Invoice=2, Deposit=3, SeparationInterest=4. Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=JournalRecType",
        "schema": {
          "type": "string",
          "enum": ["Manual", "Invoice", "Deposit", "SeparationInterest"]
        }
      },
      "JournalTypeParents": {
        "name": "journalTypeParents",
        "in": "query",
        "schema": { "type": "array", "items": { "type": "integer" } },
        "style": "form",
        "explode": true
      },
      "JournalStatuses": {
        "name": "journalStatuses",
        "in": "query",
        "description": "JournalStatus: Draft=1, Posted=2. Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=JournalStatus",
        "schema": {
          "type": "array",
          "items": { "type": "string", "enum": ["Draft", "Posted"] }
        },
        "style": "form",
        "explode": true
      }
    },
    "responses": {
      "BadRequest": { "description": "Bad request." },
      "NotFound": { "description": "Journal not found." }
    },
    "schemas": {
      "PagedJournalList": {
        "type": "object",
        "description": "Paged list of journals.",
        "properties": {
          "recordsTotal": { "type": "integer" },
          "data": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Journal" }
          },
          "lastId": { "type": "integer", "nullable": true }
        }
      },
      "JournalReversalRequest": {
        "type": "object",
        "required": ["journalID", "postingDate"],
        "properties": {
          "journalID": { "type": "integer" },
          "journalItemID": { "type": "integer" },
          "parentJournalItemIDs": {
            "type": "array",
            "items": { "type": "integer" }
          },
          "postingDate": { "type": "string", "format": "date-time" }
        }
      },
      "Journal": {
        "type": "object",
        "description": "Journal header and lines; additional fields may appear—validate against responses from your environment. Enum Help examples: JournalRecType https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=JournalRecType — JournalStatus https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=JournalStatus — RecordState https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=RecordState",
        "properties": {
          "journalID": { "type": "integer", "description": "Must be 0 on create." },
          "buID": { "type": "integer" },
          "businessUnitName": { "type": "string" },
          "journalTypeID": { "type": "integer" },
          "journalTypeName": { "type": "string" },
          "journalNumber": { "type": "integer" },
          "journalType": {
            "type": "string",
            "enum": ["Manual", "Invoice", "Deposit", "SeparationInterest"],
            "description": "JournalRecType (1–4). Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=JournalRecType"
          },
          "journalTypeParentID": { "type": "integer", "nullable": true },
          "journalStatus": {
            "type": "string",
            "enum": ["Draft", "Posted"],
            "description": "JournalStatus (1–2). Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=JournalStatus"
          },
          "journalStatusDateUtc": { "type": "string", "format": "date-time", "nullable": true },
          "journalDescription": { "type": "string" },
          "recordState": {
            "type": "string",
            "enum": ["Active", "Inactive", "Deleted", "CreatedInError"],
            "description": "RecordState (1–4). Help: https://residential.alayacare.com.au/api/Help/ResourceModel?modelName=RecordState"
          },
          "journalItemCount": { "type": "integer" },
          "invoicePostingDate": { "type": "string", "format": "date-time", "nullable": true },
          "journalItems": {
            "type": "array",
            "items": { "type": "object", "additionalProperties": true }
          },
          "props": { "type": "object", "additionalProperties": true },
          "created": { "type": "object", "additionalProperties": true },
          "lastUpdated": { "type": "object", "additionalProperties": true }
        }
      }
    }
  }
}