Skip to main content

Financial profiles and snapshots

A person's financial profile brings together what they own, what they owe, what they earn, what they spend and their employment history. In MyCRM, these are connected records with their own identities, owners and relationships.

Use the read endpoints to understand that client profile. Use a financial snapshot to submit financial information for an existing contact group and reconcile it with the records already in MyCRM.

Choose where to start​

How a financial profile connects to a person​

A person is a contacts resource. Their contactGroup links them to the related clients with whom they may share financial information. An asset, liability, income or expense connects to a person through an owners resource in its ownership relationship.

RecordWhat it representsHow it connects
AssetSomething the client owns, such as a property, savings account or vehicle.One or more owners; a real-estate asset also must have an address.
LiabilityMoney owed, such as a mortgage, credit card or personal loan.One or more owners; a mortgage can link to a real-estate asset.
IncomeEarnings or other receipts, with an amount and frequency.One or more owners; employment income can link to an employment, and rental income links to a property.
ExpenseSpending, with an amount and frequency.One or more owners; a repayment expense can be managed through a liability.
EmploymentA person's employment circumstances, employer and dates.Belongs to a contact; income can reference it.
OwnershipThe connection between a financial record and its owner.Has its own resource ID and an inferred ownershipPercentage; links to the contact and financial record.

For example, Alex and Sam can jointly own one property and its mortgage while each has a separate employment and salary. The property may appear when reading either person's profile. Count the property once when calculating a group total, using its resource type and id. Use the returned ownership percentage when you need a person's share. Existing records can have unequal shares; a snapshot submission replaces them with an equal split among its submitted owners.

An ownership ID, contact ID and asset ID identify different things. In snapshot requests, ownership: [{ "id": 1001 }] refers to contact 1001, not to an owners resource.

Financial records also have different purposes from deal records. A property is an asset; a deal security describes its use as security for a particular deal. Sharing a contact group does not make every person an owner of every financial record.

Read a person's profile​

When you know the contact ID, include the connections you need:

GET {API_BASE_URL}/jsonapi/contacts/1001?include=contactGroup,ownership.asset,ownership.liability,ownership.income,ownership.expense,employments
Authorization: Bearer {ACCESS_TOKEN}
Accept: application/vnd.api+json

For narrower reads, use the contact's ownership relationship or the individual financial endpoints listed below. See reading responses and relationships for assembling included resources.

What the financial snapshot endpoint does​

POST {API_BASE_URL}/jsonapi/contact-groups/{contactGroupId}/financial-snapshot

A snapshot supplies the financial records you want MyCRM to hold for an existing contact group. In one request it can create or update assets, expenses, incomes, liabilities and employments, connect them, and remove records omitted from collections you explicitly replace.

The endpoint applies the information to the live financial profile. Its response identifies what was created, updated or removed; the response's snapshot ID is not a saved historical version that you can retrieve later.

Beta · access by arrangement

This endpoint is in beta. Its behaviour and contract may change as it is refined. Confirm availability with LMG before depending on it in a production integration.

Temporary beta response: 423 Locked. A response with code feature_not_enabled means beta access is not enabled for the resolved user, or a valid user could not be resolved. This is a temporary restriction during the endpoint’s beta period, not an ongoing requirement for its general availability.

Normal OAuth, scope and resource-access checks still apply. Check the adviser context and arrange beta enablement before retrying; repeated retries will not unlock access. Read the beta endpoint guidance →

Before submitting​

  • Obtain a token with api.contactgroups.financialsnapshot, or an approved broader scope: api.contactgroups, api.financialsnapshot or api.
  • Supply the permitted adviser context. For client-credentials integrations, send the adviser's contact identifier in UserId; see Update information in MyCRM.
  • Resolve the target contact group and its contacts first. Snapshot ownership and employment references must select active Adult contacts in that group. The snapshot does not create people or contact groups.

The route uses the contact-group ID. Ownership and employment entries use client contact IDs. The UserId header identifies the adviser the integration is acting on behalf of.

Choose Merge or Replace for each collection​

Each collection has an independent mode: assetsMode, expensesMode, incomesMode, liabilitiesMode and employmentsMode.

ModeRecords submitted in that collectionExisting records not selected by the submission
Merge, omitted mode or nullUpdate matches and create unmatched items.Retain them, subject to expense consolidation and changes caused by linked records.
ReplaceUpdate matches and create unmatched items.Remove the eligible omitted records.

An omitted, null or empty collection in Merge mode makes no direct change to that collection. With Replace mode, the same empty collection means remove all eligible records in that collection.

Replacement applies to the contact group

A snapshot targets the whole group, not just one person's share of it. Sending only Alex's assets with assetsMode: "Replace" can deactivate Sam's omitted assets too. Use Merge when you are supplying a subset of the group's financial information.

A matched record is a complete update​

Merge preserves omitted records, not omitted fields on a record you submit. For a matched item, optional fields that are omitted or null in the snapshot data are generally cleared or reset to their defaults. Ownership is replaced with the submitted owners.

Send all snapshot fields you want that record to retain, including its existing links. For example, submitting a liability without its optional linkedAsset clears that link; submitting an employment without dateStarted clears its stored start date, even if it helped identify a match.

Submit a linked profile​

This Australian example submits a savings account and an employment with salary income. It assumes these records are new; for existing records, supply the optional values you want to retain as well.

All person, group and adviser IDs are illustrative. Replace them with accessible records in your environment. Here, assetTypeId: 15 means Savings and incomeTypeId: 19 means Salary / Wages; check the lookup data before using type IDs. Select an income-verification ID from the country-specific lookup before submitting; 1 is illustrative.

POST {API_BASE_URL}/jsonapi/contact-groups/5001/financial-snapshot
Authorization: Bearer {ACCESS_TOKEN}
UserId: 2042
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json

{
"data": {
"type": "financial-snapshots",
"attributes": {
"addresses": [{ "lid": "office", "formattedAddress": "20 Example Road, Brisbane QLD 4000", "country": "Australia" }],
"assetsMode": "Merge",
"assets": [
{
"lid": "savings",
"assetTypeId": 15,
"description": "Savings for a deposit",
"value": 25000,
"institution": "Example Bank",
"bsb": "123-456",
"accountNumber": "00123456",
"ownership": [{ "id": 1001 }]
}
],
"employmentsMode": "Merge",
"employments": [
{
"lid": "main-job",
"contactId": 1001,
"employerName": "Example Engineering",
"employmentType": "PAYG",
"employmentRoleName": "Engineer",
"employmentBasis": "FullTime",
"employerType": "Private",
"employerPhone": "+61730000000",
"address": { "lid": "office" },
"dateStarted": "2021-03-01"
}
],
"incomesMode": "Merge",
"incomes": [
{
"lid": "salary",
"incomeTypeId": 19,
"description": "Main salary",
"value": 8000,
"frequency": "Monthly",
"incomeVerificationId": 1,
"ownership": [{ "id": 1001 }],
"employment": { "lid": "main-job" }
}
]
}
}
}

Because expenses and liabilities are omitted and have no Replace mode, this request leaves those collections alone.

A lid is a request-local identifier. It lets income reference an employment or property submitted in the same request, before that record has a MyCRM resource ID.

LinkReference to supply
Income → submitted employment"employment": { "lid": "main-job" }
Income → existing employment retained in the group"employment": { "id": 8201 }
Rental income or mortgage → submitted property"linkedAsset": { "lid": "home" }
Rental income or mortgage → existing property retained in the group"linkedAsset": { "id": 8102 }
Asset or employment → submitted address"address": { "lid": "home-address" }

For employment and asset links, supply exactly one of id or lid. An existing target must remain available after the snapshot is applied. Referencing it does not itself update that target.

Local IDs are optional unless another item references the record; addresses always require one. They must be unique within their collection after trimming and are case-sensitive. They are not stored as external identifiers and do not select an existing record on the next request.

Put addresses in the snapshot's addresses array. Each must be referenced by a submitted asset or employment. An address can contain streetAddress, suburb, state, postCode, country and formattedAddress; a formatted address is assembled from the parts when omitted. These addresses maintain property and employment links, not a person's residential address history.

How Merge selects existing records​

Matching happens within the target group's active records. It does not search globally or restore previously deleted records. Replace uses the same matching rules before deciding which unmatched records to deactivate.

1. Explicit record IDs take priority​

Supply assetId, expenseId, incomeId, liabilityId or employmentId when you already know which record to update.

  • The ID is reserved before automatic matching, so another submitted item cannot take it.
  • It must identify an available record in this contact group. An invalid or out-of-group ID rejects the request; there is no fallback to creating a new record.
  • The financial type must stay the same. An employment must stay with the same contact.
  • Each existing ID can be selected only once within its collection.
  • The rest of the item must still satisfy the snapshot's validation rules.

Use an explicit ID when correcting information that otherwise identifies a record, such as an account number, employer name or income description. For example, adding "assetId": 8101 to the savings item above selects that existing Savings asset even if you correct its account number.

2. Otherwise, compare identifying details​

When no explicit ID is supplied, the endpoint compares the following details. Monetary values are not identity fields: a changed balance or salary amount can update the same record.

RecordIdentifying details used for automatic matching
Real-estate assetAsset type and normalised property address.
Deposit assetAsset type, institution, BSB and account number. Institution and account details can be omitted.
Motor vehicleAsset type, subtype, vehicle year, vehicle make and description.
Other asset types, including boatsAsset type and description.
Standard expenseExpense type, after combining submitted items of that type.
“Other” expenseExpense type and description.
IncomeIncome type and description, with linked asset/employment and ownership considered below.
Credit cardLiability type, subtype and creditor name, with account, linked asset and ownership considered below.
ATO/Centrelink debt, court-ruled child maintenance or court-ruled other debtLiability type, with account, linked asset and ownership considered below.
Other liabilitiesLiability type and creditor name, with account, linked asset and ownership considered below.
EmploymentContact, employer name and optional start date. For Unemployed, Retired, HomeDuties and Student entries, the employment type identifies the circumstance instead of an employer name.

Deposit matching applies to Savings, Cash Management, Cheque Account, Other Deposit, Pension Account, Savings Account, Term Deposit and Deposit Paid. Other asset types use their own row above.

3. Normalise formatting and account for missing details​

Text comparisons ignore case, trim leading/trailing whitespace and collapse repeated whitespace. Account comparisons remove spaces and hyphens while preserving leading zeroes. Property addresses use structured street, suburb and postcode details when complete, otherwise the formatted address; comparisons normalise common street abbreviations and Australian/New Zealand country spellings. This is formatting normalisation, not a fuzzy address search.

An existing record may lack some identifying details. A missing value can allow a less-specific match, but a different populated value normally prevents it. For example, a savings record with no account number can be compatible with an incoming Savings item that supplies one, if its other details agree. Account name is not an identity field. The type and employment contact, where applicable, must still agree; additional matching candidates can make the result ambiguous.

Missing incoming values are allowed as flexible matching components for a deposit's institution, BSB and account number, an optional asset or income description, a liability creditor (except for mortgages), a credit-card subtype, and an employment's start date. This flexibility is only for selecting a record: omitted optional values in the snapshot will normally be cleared during the update.

4. Use relationships and ownership to distinguish candidates​

  • Assets, incomes and liabilities: prefer the same set of contact owners. Different ownership can still match and will then be replaced; it is not a separate matching boundary.
  • Incomes: consider the linked asset and employment. Two different populated links cannot automatically match; a missing link on one side can be a less-preferred match.
  • Liabilities: likewise consider the linked asset and account number. Different populated account numbers cannot automatically match, even at the same creditor.
  • Employments: use supplied status, employment type and end date to prefer a closer match when the contact, employer and start-date rules allow several candidates.

The endpoint considers the submitted collection together, aiming to reuse as many compatible existing records as possible, then favouring more complete matches and closer context. It does not simply take the first record returned or process items as independent lookups. Reordering a request is not a way to choose an update target.

5. Resolve duplicates or report ambiguity​

Each existing record can match at most one submitted item. Equivalent duplicate records are handled individually, using lower existing IDs first when otherwise indistinguishable. Extra incoming items create extra records; extra existing items normally remain in Merge mode.

If more than one equally good match would select different assets, incomes, liabilities or employments, the request fails with a validation error asking for the corresponding explicit ID. It does not silently choose one merely because it has the lowest ID.

SituationResult
Same savings type and account details, different balanceUpdate the matching savings record.
Income description changes, with no incomeId and no compatible candidateCreate an income; the old income remains in Merge mode.
Correct an income description while supplying its valid incomeIdUpdate that income, retaining its ID.
Two otherwise equally suitable loans at one creditor, with different accounts, but the request omits the accountValidation error; supply liabilityId or enough identifying detail.
Same employer name for two contactsMatch only an employment belonging to the submitted contact.
Submit two identical “Other” expenses where only one matching expense existsUpdate one and create the other; the two submitted entries are not collapsed.

Store the returned resource IDs for later deliberate updates. Replaying the same identifying information usually reuses records, but lid is not an idempotency key, and changing identifying details can change which records are selected.

Automatic matching has a work limit. If a request exceeds it, the API returns 400 Bad Request without saving changes. Supply concrete IDs for existing records to reduce the matching work before retrying.

Expense consolidation and liability repayments​

Standard expenses have special Merge behaviour: the submitted entries for one expense type represent the new amount for that type, not an amount to add to its existing balance.

When several standard expenses share a type, their values are annualised using their frequencies, summed, and converted back to the shortest submitted frequency, rounded to two decimal places. Their owners are combined and their descriptions are combined. For example, 100 per month for contact A plus 1,200 per year for contact B becomes 200 per month for contacts A and B.

One existing standard expense is updated, or one is created if none matches. Other existing standard expenses of that submitted type are deactivated even in Merge mode. Omitted types remain unchanged. If several submitted entries combine into one, they may nominate at most one distinct expenseId.

“Other” expense types keep separate items and match by type and description.

Repayment expenses are managed through liabilities. Supply repayment and repaymentFrequency on the liability rather than submitting its repayment expense directly. A supplied repayment requires a frequency, including when the repayment is zero. Setting repayment to zero, omitting it or supplying null unlinks its existing expense. That expense remains stored when expenses use Merge, although ordinary-expense visibility rules may hide it. If expenses are being replaced in the same snapshot, it is deactivated. Deleting a liability also deactivates its linked repayment expenses. Replacing ordinary expenses alone does not remove repayments linked to retained liabilities.

Ownership, relationships and validation​

The endpoint validates the complete proposed state before saving the changes.

  • Ownership: supply at least one active Adult contact from the group for each asset, income, expense and liability. The snapshot replaces existing ownership and divides it equally among distinct submitted contacts, with rounding to total 100%. It does not accept custom percentages; updating a jointly owned record can therefore replace an existing unequal split.
  • Employment income: Salary / Wages, Bonus, Commission, Company Profit Before Tax and Foreign Income require an employment link. Other supported employment-income types can also have one. Any income linked to employment must have exactly one owner: that employment's contact, and an incomeVerificationId available for the group country.
  • Rental income: must reference a real-estate asset. New Zealand rentals also require nzRentalType and nzRentalVerificationTypeId; omit all nz fields for Australian submissions. Outside New Zealand, rental income cannot link to an owner-occupied property.
  • Mortgages: only mortgage liabilities can have linkedAsset, and the target must be real estate. Property ownership and the ownership of its income or mortgage are independent.
  • Lookups: types and subtypes must exist and agree. Expenses accept the available expense types and categories; repayment types managed through liabilities cannot be entered directly.
  • Lenders: institution and creditor names are resolved against active lenders in the group's country using the full name, ignoring case and surrounding spaces. Unknown names remain free text; ambiguous lender names reject the request.

Amounts use the contact group's local currency; the snapshot does not accept a currency selector or silently convert a known foreign-currency record. Other field rules include valid enum values, date ranges, amount limits and country-specific verification types. Dates use YYYY-MM-DD. Frequencies use names such as Weekly, Fortnightly, Monthly or Yearly; do not assume every amount is monthly. Gross/net classification defaults to gross except Other Net Income; Salary / Wages can explicitly use either classification through nzIsGross in New Zealand.

Replacement and linked deletions​

Replacement has effects beyond the array being replaced:

  • Removing an asset also removes its omitted linked incomes and liabilities, even if those collections use Merge. Submit a dependant with a valid cleared or changed link if it should survive; required links, such as a rental income's property, must still be supplied.
  • A retained income cannot point to a removed employment. Retain the employment, relink the income, or remove the income in the same snapshot.
  • Asset removal can also remove its use as security on eligible deals and affect the associated funding information. The deal's status determines whether these related changes apply.
  • Existing expenses and incomes with types outside the supported snapshot contract are preserved when replacing those collections. Removing an asset can still remove its linked income.
  • Property rental/mortgage indicators and relevant lender associations are refreshed when affected links change.

Read the returned operations to see derived changes as well as the records you submitted.

Read the result and handle retries​

A successful request returns 200 OK. For the earlier example, if all three records are new, a response can contain:

{
"data": {
"type": "financial-snapshots",
"id": "6b2e6349-b265-453a-bd38-1240f0e192d0",
"attributes": {
"operations": {
"created": [
{ "type": "assets", "id": "8101", "meta": { "lids": ["savings"] } },
{ "type": "incomes", "id": "8301", "meta": { "lids": ["salary"] } },
{
"type": "employments",
"id": "8201",
"meta": { "lids": ["main-job"] }
}
],
"updated": [],
"deleted": []
}
}
}
}

Actual IDs and list order may differ. Reconcile using type and id, and use optional meta.lids to associate a result with your submitted local IDs. Usually meta.lids will contain at most one entry but a consolidated expense can report several local IDs for one saved resource. Derived changes may have no local IDs.

A matched record appears in updated even when its values are unchanged. Results can also include managed expenses, indirectly updated assets and deleted deal-securities. They do not include complete copies of the saved financial records. Read the relevant resources back when needed. include is not supported on the snapshot POST. An optional fields[financial-snapshots]=operations selects the response attribute; it does not limit which inputs are processed.

ResponseWhat it means for this operation
400 Bad RequestMalformed input, unavailable IDs, ambiguous matches or an invalid final relationship. Correct the request before resubmitting.
422 Unprocessable EntityField validation failed, such as a missing property address or repayment frequency. Correct every reported error and resubmit the complete intended request.
401 / 403Check the token, snapshot scope and permitted adviser context.
404 Not FoundThe contact group may not exist or may be outside your access.
409 ConflictThe snapshot could not obtain exclusive access for this group. Wait briefly and retry a limited number of times.
423 LockedBeta access is not enabled for the resolved adviser, or a valid adviser could not be resolved. Check context and arrange beta access; repeated retries will not enable it.

Errors use the JSON:API errors array. Keep each error's status, code, title and detail; use source.pointer when present, but do not assume every error includes a field pointer. Descriptive wording may vary. See error handling and beta access.

The changes in a snapshot are applied together. A validation failure does not save part of the request. This does not make the preliminary GETs and the later POST one transaction: if another writer changed the profile in between, review current data before submitting a replacement.

A timeout or server error does not prove that nothing changed: your update may already have been applied. Read back the current profile before deciding how to retry an uncertain write. Keep the same intended records and use known resource IDs where available; a replay can report those records as updated again.

Financial resources and reference data​

Use reference identifiers for mappings and refresh lookup data deliberately. Keep amount, frequency, currency and gross/net meaning together when interpreting a financial value.

The beta snapshot also uses GET /jsonapi/income-verification-types and GET /jsonapi/rental-verification-types for verification choices. Use the intended adviser context and the correct country's choices.

For ongoing integration design, see synchronisation and rate limits.