Skip to main content

Asset finance referrals and their related records

An asset finance referral summary brings together its proposed loan amount, adviser and applicants. Use its summary to report on referral progress through review, approval and completion.

Availability

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​

OperationEndpointScope
Search accessible referralsGET /jsonapi/asset-referralapi.diversifiedassetreferrals.search
Read a referral by IDGET /jsonapi/asset-referral/{id}api.diversifiedassetreferrals.read

Applicable broader scopes, such as api.diversifiedassetreferrals, can also satisfy these requirements. Request the granted scopes when obtaining the token. Scope names use diversifiedassetreferrals, while URLs and resource types use asset-referral. See choosing scopes.

The api.deals and api.diversifiedassetdeals scopes do not grant access to asset referrals.

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 referral 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 asset-referral and use the existing positive Engagement V1 ID, rendered as a string. Preserve both type and id when storing a reference. Keep these identities separate from asset-deal, commercial-deal, deals and client financial assets.

AttributeValue and meaning
titleReferral title, which can be null.
statusPublished status code, or null when the source status is missing.
statusLabelDisplay label, which can be null. Use status for programmatic mapping.
amountProposed loan amount stored on the referral.
createdDateCreation date, or null.
loanReferenceLoan reference, which can be null; it is distinct from the public referral ID.
lenderNameDisplay-only lender name, including free-text names, or null.
referralSentDateReferral sent date, or null.
approvalDateApproval date, or null.
settlementDateSettlement 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 referral'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.

Status, status label, lender name and loan reference come from the stored referral loan details. A missing status or label is null; a missing loan reference can be an empty string.

Published status values are NewReview, Submitted, Approved, Committed, ClosedWon, ClosedLost, NotProceededWith. 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.

Source statuses are normalized as follows. The returned statusLabel retains the source wording.

Source statusPublic status
Draft or ReviewNewReview
Closed - WonClosedWon
Closed - LostClosedLost

Filter using the published status: equals(status,'NewReview') also matches stored Draft and Review values. Settled is not a published referral status; use the returned status and settlement date independently.

RelationshipResource type in dataMeaning
adviseradvisersThe accessible current adviser, or null.
applicantscontactsAccessible people with active Applicant links; an array that can be empty.
applicantBusinessesbusinessAccessible 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.

Asset finance deals use the separate asset-deal resource, with different amounts, statuses and lifecycle fields.

Read a referral​

Replace the illustrative ID with an accessible asset finance referral:

GET {API_BASE_URL}/jsonapi/asset-referral/7001
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": "asset-referral",
"id": "7001",
"attributes": {
"title": "Vehicle finance referral",
"status": "Approved",
"statusLabel": "Approved",
"amount": 45000,
"createdDate": "2026-01-15",
"loanReference": "EXAMPLE-001",
"lenderName": "Example lender",
"referralSentDate": "2026-01-20",
"approvalDate": null,
"settlementDate": null
}
}
}

Relationships are omitted unless requested through include. Their omission does not mean that the referral has no adviser or applicants.

Search and filter referrals​

Collection reads return 200 OK with a data array, including an empty array when no referrals are returned on the requested page. Use a single filter parameter and combine conditions with and(...).

Filter expressionMeaning
equals(status,'Approved')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 approved referrals created during January. Query expressions are shown before URL encoding:

GET {API_BASE_URL}/jsonapi/asset-referral?filter=and(equals(status,'Approved'),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].

Filter matches and applicant roles

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 referral 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, referralSentDate, approvalDate 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 referral'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 referrals match. See querying collections for navigating pages.

Request the adviser, person applicants and business applicants together:

GET {API_BASE_URL}/jsonapi/asset-referral/7001?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/asset-referral/7001?include=adviser,applicants,applicantBusinesses&fields[asset-referral]=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 referrals. Likewise, sort[applicants]=-id orders the included applicants. Use the top-level filter=has(applicants,equals(id,'1001')) expression when selecting referrals by an involved person, subject to the role distinction above.

Tasks do not expose a dedicated asset-referral relationship. The task's assetFinanceDiversifiedDeal relationship identifies an asset-deal, not an asset-referral; do not substitute referral identifiers there.

Handle errors and empty results​

SymptomWhat to check
400 Bad RequestCheck status spelling, supported filters/sort fields, duplicate criteria, date-bound order, include/fieldset names and page size.
401 or 403Check the token, requested search/read scope and permitted adviser context.
404 Not FoundThe referral ID may be non-positive, missing, inactive, deleted, inaccessible or in a different category. The response does not distinguish these cases.
200 OK with data: []No referrals were returned on this page. Check the page number, filters and access agreement.
500 Internal Server ErrorAn 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 referral ID in the member URL returns 404.

See errors, rate limits and synchronisation for error handling and retry guidance.

Further reading​