Commercial finance deals and their related records
A commercial finance deal connects an application with its financing amount, adviser and applicants. Use its summary to report on application progress through review, approval and settlement.
The current API implementation and its approved specification include these read endpoints. This portal's imported API reference still uses an older specification that omits them. Confirm availability in your target environment and your application's access with LMG before running the examples.
Available operations and access
| Operation | Endpoint | Scope |
|---|---|---|
| Search accessible deals | GET /jsonapi/commercial-deal | api.diversifiedcommercialdeals.search |
| Read a deal by ID | GET /jsonapi/commercial-deal/{id} | api.diversifiedcommercialdeals.read |
Applicable broader scopes, such as api.diversifiedcommercialdeals, can also satisfy these requirements. Request the granted scopes when obtaining the token. Scope names use diversifiedcommercialdeals, while URLs and resource types use commercial-deal. See choosing scopes.
Residential api.deals scopes do not grant access to these resources.
Both collection and member endpoints also support HEAD, with the same respective search/read scopes and no response body.
Supply Authorization: Bearer {ACCESS_TOKEN} and Accept: application/vnd.api+json. The examples also supply a permitted adviser contact ID in UserId. With resolved adviser context, user access restrictions further narrow the application's mandate; without a resolved user, mandate restrictions still apply. Filters cannot widen that access. See adviser context and data visibility.
The endpoints are read-only. They do not create applications, update statuses, change applicant links or support POST, PATCH, PUT or DELETE. Separate deal relationship URLs, such as /{id}/applicants and /{id}/relationships/applicants, return 404; use include on a collection or member read.
Fields and relationships
Resources have type commercial-deal and use the existing positive Engagement V1 ID, rendered as a string. Preserve both type and id when storing a reference. These IDs are separate from residential deals.
| Attribute | Value and meaning |
|---|---|
title | Deal title, which can be null. |
status | Published status code, or null when the source status is missing. |
statusLabel | Display label, which can be null. Use status for programmatic mapping. |
amount | Sum of commercial loan-split amounts, excluding deleted splits; missing amounts contribute 0. |
createdDate | Creation date, or null. |
loanReference | Loan reference, which can be null; it is distinct from the public deal ID. |
lenderName | Display-only lender name, including free-text names, or null. |
submittedDate | Application lodgement date, or null. |
decisionDate | Decision date, or null. |
settlementDate | Settlement date, or null. |
Dates use YYYY-MM-DD without a time or offset. The creation date is derived from the stored UTC timestamp. Do not synthesize timestamps, or infer a deal's status from a missing lifecycle date. Preserve the returned amount without assuming a currency conversion. The summary does not contain an itemized loan-split, security or product breakdown. There is no lender relationship to include. estimatedSettlementDate is not a public attribute; settlementDate does not fall back to the estimated date. Nodifi identifiers, lender logos and closed-lost reasons are also absent from these summaries.
Missing labels and loan references can also be empty strings; do not assume every missing value is null.
Published status values are NewApplication, Review, Submitted, Approved, Deferred, Settled, ClosedLost. Use their exact spelling and case in filters. A missing source status returns null; an unsupported source status returns an error rather than an invented default.
| Relationship | Resource type in data | Meaning |
|---|---|---|
adviser | advisers | The accessible current adviser, or null. |
applicants | contacts | Accessible people with active Applicant links; an array that can be empty. |
applicantBusinesses | business | Accessible business/entity applicants with active Applicant links; an array that can be empty. |
A Guarantor link alone does not make someone an applicant. Person and business IDs are separate even when their numeric values coincide. The adviser relationship and adviser.id filter use the adviser family/resource ID, whereas UserId takes the adviser contact ID.
Read a deal
Replace the illustrative ID with an accessible commercial finance deal:
GET {API_BASE_URL}/jsonapi/commercial-deal/6001
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
A successful read returns 200 OK with one resource in data. For example:
{
"data": {
"type": "commercial-deal",
"id": "6001",
"attributes": {
"title": "Business premises finance",
"status": "Deferred",
"statusLabel": "Deferred",
"amount": 1250000,
"createdDate": "2026-01-15",
"loanReference": "EXAMPLE-001",
"lenderName": "Example lender",
"submittedDate": "2026-01-20",
"decisionDate": null,
"settlementDate": null
}
}
}
Relationships are omitted unless requested through include. Their omission does not mean that the deal has no adviser or applicants.
Search and filter deals
Collection reads return 200 OK with a data array, including an empty array when no deals are returned on the requested page. Use a single filter parameter and combine conditions with and(...).
| Filter expression | Meaning |
|---|---|
equals(status,'Deferred') | Published status for this category. |
equals(adviser.id,'21') | Latest active assignment's adviser resource ID. |
has(applicants,equals(id,'1001')) | Active involved-person link to an accessible contact, regardless of role. |
has(applicantBusinesses,equals(id,'2001')) | Active involved-business link to an accessible business, regardless of role. |
greaterOrEqual(createdDate,'2026-01-01') | Inclusive lower creation-date bound in UTC. |
lessOrEqual(createdDate,'2026-01-31') | Inclusive upper creation-date bound in UTC. |
For example, find deferred deals created during January. Query expressions are shown before URL encoding:
GET {API_BASE_URL}/jsonapi/commercial-deal?filter=and(equals(status,'Deferred'),greaterOrEqual(createdDate,'2026-01-01'),lessOrEqual(createdDate,'2026-01-31'))&sort=-createdDate&page[number]=1&page[size]=10
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Each criterion may appear only once. or(...), not(...), duplicate criteria and reversed date ranges are rejected. Repeated filter parameters are combined as OR by the JSON:API framework and are also unsupported here. Use filter=... expressions rather than aliases such as filter[status] or filter[adviserId].
The current implementation of has(applicants,...) and has(applicantBusinesses,...) matches active involved-party links, including Guarantors. The returned relationships contain only active Applicant links. A deal can therefore match either filter without returning the matching party in its applicant relationship. Do not use a filter match alone as proof of an Applicant role.
Use positive adviser, contact and business IDs. An inaccessible applicant ID cannot broaden the results; a filter for it returns an empty collection.
Sorting and pagination
Use page[number] starting at 1 and page[size] from 1 to 100 (default 10). Unbounded pages are rejected. Sort by id, createdDate, submittedDate, decisionDate or settlementDate; prefix a field with - for descending order. Multiple sort fields are comma-separated, such as sort=-settlementDate,createdDate, and each field may appear only once.
The default order is newest creation first, then ID ascending. Creation-date sorting uses the full stored timestamp, even though the response exposes only the date. Lifecycle dates and their sort keys use the first non-deleted date record by ID for the relevant category; missing dates remain null. Access restrictions apply before pagination and the collection's meta.totalResources count.
If a selected deal's summary is no longer available, it is omitted without refilling the page or recalculating the count. A short or empty page therefore does not necessarily mean that no other accessible deals match. See querying collections for navigating pages.
Include related records and select fields
Request the adviser, person applicants and business applicants together:
GET {API_BASE_URL}/jsonapi/commercial-deal/6001?include=adviser,applicants,applicantBusinesses
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Match each identifier in data.relationships to a resource in included using both type and ID. For example, contacts/1001 and business/1001 identify different parties. Related records have their own access checks, so handle a null adviser and empty person or business arrays. Applicant ordering is not guaranteed unless you request a supported related-resource sort.
To retrieve selected summary fields and related identities only:
GET {API_BASE_URL}/jsonapi/commercial-deal/6001?include=adviser,applicants,applicantBusinesses&fields[commercial-deal]=title,status,amount,createdDate,adviser,applicants,applicantBusinesses&fields[advisers]=id&fields[contacts]=id&fields[business]=id
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Keep the relationship names in the primary fieldset when you need their identifiers. include selects related resources, while fields[...] selects returned fields. A field omitted by a fieldset is not evidence that its stored value is empty. These query options also work on collection reads. See relationships and reading responses.
Filter an included collection
With include=applicants, a scoped filter such as filter[applicants]=equals(id,'1001') restricts the included applicants; it does not select the top-level deals. Likewise, sort[applicants]=-id orders the included applicants. Use the top-level filter=has(applicants,equals(id,'1001')) expression when selecting deals by an involved person, subject to the role distinction above.
Task links
A task's commercialFinanceDiversifiedDeal relationship uses type commercial-deal and the same Engagement V1 ID. Use that identifier with the member endpoint above to read the deal summary. The task has its own separate ID.
Access to a task does not automatically grant access to its deal. Reading the task and reading the deal require their respective scopes and record permissions. See Read a task for the task response contract.
Handle errors and empty results
| Symptom | What to check |
|---|---|
400 Bad Request | Check status spelling, supported filters/sort fields, duplicate criteria, date-bound order, include/fieldset names and page size. |
401 or 403 | Check the token, requested search/read scope and permitted adviser context. |
404 Not Found | The deal ID may be non-positive, missing, deleted, inaccessible or in a different category. The response does not distinguish these cases. |
200 OK with data: [] | No deals were returned on this page. Check the page number, filters and access agreement. |
500 Internal Server Error | An unsupported source status can fail a read. Do not map that failure to a default status; retain the error details for support. |
Unsupported writes such as POST to the collection or PATCH/DELETE to a member return 405 Method Not Allowed.
Use positive IDs in filters: the current ID parser can return 500 for zero adviser or person-contact IDs before normal query validation runs. Negative filter IDs are rejected with 400. A non-positive deal ID in the member URL returns 404.
See errors, rate limits and synchronisation for error handling and retry guidance.