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
- Build your first request after checking access and the target contact group.
- Choose Merge or Replace before importing a partial or complete profile.
- Understand matching before replaying a request or changing identifying details.
- Handle results and errors and read back the saved records.
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.
| Record | What it represents | How it connects |
|---|---|---|
| Asset | Something the client owns, such as a property, savings account or vehicle. | One or more owners; a real-estate asset also must have an address. |
| Liability | Money owed, such as a mortgage, credit card or personal loan. | One or more owners; a mortgage can link to a real-estate asset. |
| Income | Earnings 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. |
| Expense | Spending, with an amount and frequency. | One or more owners; a repayment expense can be managed through a liability. |
| Employment | A person's employment circumstances, employer and dates. | Belongs to a contact; income can reference it. |
| Ownership | The 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.
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.financialsnapshotorapi. - 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.
| Mode | Records submitted in that collection | Existing records not selected by the submission |
|---|---|---|
Merge, omitted mode or null | Update matches and create unmatched items. | Retain them, subject to expense consolidation and changes caused by linked records. |
Replace | Update 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.
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.
Link new and existing records
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.
| Link | Reference 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.
| Record | Identifying details used for automatic matching |
|---|---|
| Real-estate asset | Asset type and normalised property address. |
| Deposit asset | Asset type, institution, BSB and account number. Institution and account details can be omitted. |
| Motor vehicle | Asset type, subtype, vehicle year, vehicle make and description. |
| Other asset types, including boats | Asset type and description. |
| Standard expense | Expense type, after combining submitted items of that type. |
| “Other” expense | Expense type and description. |
| Income | Income type and description, with linked asset/employment and ownership considered below. |
| Credit card | Liability type, subtype and creditor name, with account, linked asset and ownership considered below. |
| ATO/Centrelink debt, court-ruled child maintenance or court-ruled other debt | Liability type, with account, linked asset and ownership considered below. |
| Other liabilities | Liability type and creditor name, with account, linked asset and ownership considered below. |
| Employment | Contact, 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.
| Situation | Result |
|---|---|
| Same savings type and account details, different balance | Update the matching savings record. |
Income description changes, with no incomeId and no compatible candidate | Create an income; the old income remains in Merge mode. |
Correct an income description while supplying its valid incomeId | Update that income, retaining its ID. |
| Two otherwise equally suitable loans at one creditor, with different accounts, but the request omits the account | Validation error; supply liabilityId or enough identifying detail. |
| Same employer name for two contacts | Match only an employment belonging to the submitted contact. |
| Submit two identical “Other” expenses where only one matching expense exists | Update 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
incomeVerificationIdavailable for the group country. - Rental income: must reference a real-estate asset. New Zealand rentals also require
nzRentalTypeandnzRentalVerificationTypeId; omit allnzfields 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.
| Response | What it means for this operation |
|---|---|
400 Bad Request | Malformed input, unavailable IDs, ambiguous matches or an invalid final relationship. Correct the request before resubmitting. |
422 Unprocessable Entity | Field validation failed, such as a missing property address or repayment frequency. Correct every reported error and resubmit the complete intended request. |
401 / 403 | Check the token, snapshot scope and permitted adviser context. |
404 Not Found | The contact group may not exist or may be outside your access. |
409 Conflict | The snapshot could not obtain exclusive access for this group. Wait briefly and retry a limited number of times. |
423 Locked | Beta 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.
- Assets, asset types, asset subtypes and asset categories.
- Liabilities, liability types and liability categories.
- Incomes, income types and income categories.
- Expenses, expense types and expense categories.
- Property types.
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.