Journals API — integration guide

This guide describes how to call the finance journals HTTP API in AlayaCare Residential. Use it together with the OpenAPI file for request and response shapes.

OpenAPI: journals_api.openapi.json (OpenAPI 3.0.3 — HTTP contract under /Journals/Journal relative to the Residential API base, commonly with an /api prefix; see info, servers, and externalDocs in the file for an example Help index URL).

Enumeration names and numeric values for each deployment are documented on that tenant’s API Help pages (see Enumeration values and API Help below). The OpenAPI externalDocs points to an example Help index: https://residential.alayacare.com.au/api/Help (replace the host with yours).

Table of Contents

Base URL and paths

  • Your integration partner or tenant administrator will supply the Residential API base URL (scheme, host, port, and any path prefix).
  • Journal operations use the resource path /api/Journals/Journal relative to that base (so the full path is typically {baseUrl}/api/Journals/Journal and its sub-paths).
  • Requests and responses use application/json. Date/time fields are in UTC unless your agreement states otherwise.

Authentication and access

Callers must be authenticated using the same mechanism as your other Residential API integrations (for example browser session or bearer token, depending on how your environment is set up).

The signed-in identity needs finance journal access appropriate to each operation:

  • Read — search journals, load one journal, read payment status
  • Write — prepare a new journal shell, create, update, validate without saving, post, reverse
  • Delete — soft-delete or purge

Exact permission names are configured in the product; map the operations above to the roles or API access your administrator assigns.

Enumeration values and API Help

The Residential API publishes Help metadata for many model types. Use this pattern with your API root (the same base you use for /api/Journals/...):

{apiRoot}/Help/ResourceModel?modelName={TypeName}

Example reference host (replace the host with yours for non-production or other regions):

Type Help URL (example)
JournalRecType (journal category) JournalRecType
JournalStatus (draft vs posted) JournalStatus
RecordState (active / deleted / etc.) RecordState
MatchCriteriaStringType (text search mode for list filters) MatchCriteriaStringType
PaymentStatus (payment settlement endpoint) PaymentStatus
PaymentMethod (often on journal line items) PaymentMethod

The Help pages are the authoritative list of names and numeric values for that deployment. The tables below match the usual contract and are provided for convenience.

Wire format: Depending on environment and serializer settings, enums may appear in JSON as names (e.g. Draft) or as numbers (e.g. 1). When in doubt, compare with a live response and with Help for your host.

JournalRecType (journalType on journal and list filters)
Name Numeric value Typical meaning
Manual 1 Manually created journal
Invoice 2 Journal tied to invoice workflow
Deposit 3 Journal tied to deposit workflow
SeparationInterest 4 Separation interest journal

When filtering by journalTypeParents, the ids refer to invoices when journalType is Invoice, and to deposits when journalType is Deposit.

JournalStatus (journalStatus on journal; journalStatuses list filter; line item status where applicable)
Name Numeric value
Draft 1
Posted 2
RecordState (recordState on journal and line items)
Name Numeric value
Active 1
Inactive 2
Deleted 3
CreatedInError 4

List filters includeActive, includeInactive, includeDeleted, and includeError control which of these are returned.

MatchCriteriaStringType (match on list)
Name Numeric value Typical use
Full 1 Exact match
PartialStarting 2 Starts with
PartialAnywhere 3 Contains
Like 4 SQL-style LIKE pattern
PaymentStatus (GET …/PaymentStatus response body)
Name Numeric value
Draft 1
Posted 2
Processing 3

Response may be null when the journal has no applicable payment status.

PaymentMethod (journal line items, when present)
Name Numeric value
Cash 10
Cheque 20
CreditCard 30
DirectDebit 40
EFT 50

List journals (paged)

GET …/api/Journals/Journal

Returns a JSON object with:

  • recordsTotal — number of matching journals (after access rules are applied)
  • data — array of journal objects
  • lastId — optional paging hint when present
Query parameters

Record state and audit

Parameter Type Description
includeActive boolean Include active journals (usually true when omitted).
includeInactive boolean Include inactive journals.
includeDeleted boolean Include deleted journals.
includeError boolean Include journals marked created in error.
createdDateUtcMin, createdDateUtcMax date-time Filter by created time (UTC).
lastUpdatedDateUtcMin, lastUpdatedDateUtcMax date-time Filter by last updated time (UTC).
match string Text match mode; see MatchCriteriaStringType above and Help.

Journal filters

Parameter Type Description
includeItems boolean When true, each journal in data includes line items.
journals integer, repeated Filter by journal id; repeat the parameter for each id (…&journals=1&journals=2).
businessUnits integer, repeated Filter by business unit id.
businessUnitNames string, repeated Filter by business unit name.
journalTypes integer, repeated Filter by journal type id.
journalTypeNames string, repeated Filter by journal type name.
journalNumber integer Filter by journal number.
journalType string JournalRecType — see Help and table above.
journalTypeParents integer, repeated Parent ids; meaning depends on journalType (for example invoice or deposit context).
journalStatuses string, repeated JournalStatus — see Help and table above.
journalStatusDateUtcMin, journalStatusDateUtcMax date-time Filter by journal status date (UTC).
journalDescription string Filter by description (honours match).
props object Filter by custom properties when your integration uses them.
sort object(s) Sorting; use sortColumn and sortDirection as agreed with your field names.
skip integer Non-negative offset for paging.
limit integer Page size; when greater than zero, the service returns a slice of the result set.

Responses: 200 with the paged wrapper. 4xx when validation fails (details in the error body format used by your Residential API).

Initialize a new journal (shell)

GET …/api/Journals/Journal/Initialize

Returns a 200 response whose body is a journal object suitable for editing before create. Optional query parameters may be added in future; ignore unknown parameters defensively.

Requires write access (same as create).

Get one journal

GET …/api/Journals/Journal/{journalID}

  • journalID — positive integer.

200 — journal object. 404 — not found.

Payment status

GET …/api/Journals/Journal/{journalID}/PaymentStatus

Returns direct-debit settlement tracking for the journal when applicable.

Response body is a PaymentStatus numeric code or null when not applicable. See PaymentStatus Help and the table under PaymentStatus in Enumeration values and API Help.

200 in all cases where the journal exists.

Create journal

POST …/api/Journals/Journal
POST …/api/Journals/Journal/{validateOnly} — optional path segment true or false

Body: journal JSON (see Journal resource below).

  • On create, journalID must be 0. Otherwise the service responds with 400.
  • validateOnly = true (path …/true): validate only, 200, empty body.
  • validateOnly = false or omitted: save, 201, Location header points to the new journal, body typically empty.

Update journal

PUT …/api/Journals/Journal/{journalID}
PUT …/api/Journals/Journal/{journalID}/{validateOnly}

Body: journal JSON. The service aligns the journal’s id with journalID in the path. Same validate-only behaviour as create; successful save returns 200.

Post journal

PUT …/api/Journals/Journal/{journalID}/Post

Commits a draft journal. Path uses Post with that exact casing.

200 on success; 400 when the id is invalid.

Delete journal

DELETE …/api/Journals/Journal/{journalID}
DELETE …/api/Journals/Journal/{journalID}/{purge}

  • Omit purge or set it to false for a normal (soft) delete.
  • purge = true removes the row from the database (irreversible).

200 on success.

Reverse journal

POST …/api/Journals/Journal/Reverse

Body JSON:

Field Type Required
journalID integer Yes (non-zero)
journalItemID integer Depends on your reversal scenario
parentJournalItemIDs array of integers Optional
postingDate date-time Yes

201 — reversal journal created; Location header and response body contain the new journal. 4xx on validation or business-rule failure.

Reverse draft settlement

POST …/api/Journals/Journal/ReverseDraftSettlement/{parentJournalItemId}/{account}

  • parentJournalItemId — positive integer.
  • account — account identifier string.

200 on success; 400 if parameters are invalid.

Journal resource (JSON body)

Property names are camelCase in JSON. Common fields:

Field Notes
journalID 0 on create; set on read/update.
buID Business unit id.
businessUnitName Resolved or display name when present.
journalTypeID, journalTypeName Journal type.
journalNumber Display number.
journalType JournalRecType — Help; see enum table above.
journalTypeParentId Optional link to parent business object.
journalStatus, journalStatusDateUtc JournalStatus — Help; see enum table above.
journalDescription Free text.
recordState RecordState — Help; see enum table above.
journalItemCount Count when items are not expanded.
journalItems Line items (amounts, accounts, settlement, links to invoice/deposit/entity, payment details, etc.). Payment fields often use PaymentMethod — Help.
props Custom key/value properties when used.
created, lastUpdated Audit blocks (typically user and UTC time).
invoicePostingDate Optional posting date for invoice-related flows.

For a strict machine-readable list of fields, rely on journals_api.openapi.json and live responses from your non-production environment.

Errors

Validation and client errors use your environment’s standard JSON error format (message, field-level errors where applicable). Integrations should log correlation ids if your gateway provides them.