Deals and their related records
A deal connects contacts with a residential loan application. There are separate entities to represent commercial and asset deals. Its related records can include contacts, participants, notes, loan structure and securities.
Contacts and participants: who is involved, and in what role?
A contact holds information about a person, such as their name, email address and phone number. A participant describes that person's involvement in a particular deal, including whether they are an applicant, guarantor or dependant.
For example, Alex might be an applicant on their own home loan and a guarantor on a family member's loan. Both deals can link to Alex's same contact record. Each deal has a separate participant record describing Alex's role in that deal.
| Relationship on a deal | What it gives you | When to use it |
|---|---|---|
contacts | The linked contact records. | You need to know who is linked to the deal or retrieve information about them such as their email addresses. |
participants | The deal-specific participation, their role and link to their contact record. | You need to distinguish applicants, guarantors and dependants, or report on each person's role. |
These are two views of the deal's connections. The contacts relationship follows the contact links on its participant records; it is not a list of everyone in the wider contact group. Being linked as a contact does not by itself mean someone is an applicant. Use the participant's role to determine that.
Retrieve the roles and contact details together
With the appropriate access, request the deal's participants and include their contacts:
GET {API_BASE_URL}/jsonapi/deals/5001/participants?include=contact
Authorization: Bearer {ACCESS_TOKEN}
Accept: application/vnd.api+json
The response's data contains deal-participants resources. Each can have isApplicant, isGuarantor and isDependent attributes, with contact details in included when available. Match relationships.contact.data to the included contact using its type and id.
A participant has its own ID. For example, participant 7001 could link contact 1001 to deal 5001; those identifiers are not interchangeable.
Query from the nearest resource
Use a deal read when you know its ID. Use a collection query when you need to find deals. Fetch a related resource when you need its fields, or its relationship endpoint when only identifiers are required.
Deeply including every related record can be costly. Start with the output your integration actually needs and choose a narrow fieldset and a small set of relationships.
Edit a deal's name and BID notes
Use PATCH a deal with api.deals.update or a broader applicable scope. Send the bearer token, a permitted adviser contact ID in UserId, and the JSON:API headers. Replace the example IDs with records your application may change.
A name-only edit is allowed at any stage, subject to access checks. The name is limited to 200 characters. BID notes can be changed only before submission. Send only the attributes you intend to change; omitted attributes and nested rationale fields retain their values.
For an Australian deal still in pre-submission:
PATCH {API_BASE_URL}/jsonapi/deals/5001
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "deals",
"id": "5001",
"attributes": {
"name": "Home loan refinance",
"auRationale": {
"summary": "Reasons for the lending recommendation."
}
}
}
}
Choose the rationale for the adviser's country
Read data.attributes.countryCode from the deal's adviser. Use auRationale for AU and nzRationale for NZ. Supplying the other country's rationale is rejected.
For a New Zealand deal, replace the example's attributes with:
{
"nzRationale": {
"summary": "Reasons for the lending recommendation.",
"lenderPreferences": "The client's lender preferences.",
"loanStructure": "Reasons for the recommended structure.",
"productFeatures": "Reasons for the recommended features."
}
}
Both rationale fields are write-only: they are not returned by GET or in the PATCH response. A successful PATCH can return 200 OK with a resource or 204 No Content. You can read the name back, but cannot verify BID notes through a subsequent GET.
Create and update loan structures
A loan structure belongs to one residential deal and has its own ID. Both creation and updates require the deal to be in pre-submission. Use api.deal-structures.create for POST and api.deal-structures.update for PATCH, or broader applicable scopes. Reading the result separately requires the corresponding read access.
Create through POST a deal structure, linking the existing deal in relationships.deal:
POST {API_BASE_URL}/jsonapi/deal-structures
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "deal-structures",
"attributes": {
"loanStructureType": "PrincipalInterest",
"loanTermYears": 30,
"amount": 500000,
"rateType": "Variable",
"interestRate": 0.055,
"paymentAmount": 2800,
"repaymentFrequency": "Monthly"
},
"relationships": {
"deal": { "data": { "type": "deals", "id": "5001" } }
}
}
}
POST returns 201 Created; save the structure's data.id. Existing structure IDs can also be retrieved from the deal's structures.
Use that structure ID in PATCH a deal structure:
PATCH {API_BASE_URL}/jsonapi/deal-structures/6001
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
{
"data": {
"type": "deal-structures",
"id": "6001",
"attributes": { "paymentAmount": 2900 }
}
}
Omitted attributes remain unchanged. The deal relationship is set on creation and cannot be reassigned by PATCH. Read the result through GET a deal structure.
Interest rates use decimal fractions: 0.055 means 5.5%. An existing structure's interestRate cannot be changed when a product is selected. Other writable fields include account number, interest-only term, fixed-rate dates, rateTermYears, repayment frequency and LMI values. rateTypePeriodMonths and interestOnlyExpiryDate are read-only; consult the operation's schema before copying response fields into a write.
Statuses and reference data
System statuses (i.e. dealStatus) are consistent regardless of broker and business. They represent common statuses that occur in a residential deal, such as Lead, Unconditionally Approved and Settled. System statuses are not directly maintained within MyCRM but are inferred from the definition of the pipeline statuses (i.e. customStatusName). Pipeline statuses are customised per-business and match what appears in MyCRM. Using dealStatus is recommended for implementations which need to work across multiple businesses.
Read custom statuses
Custom statuses have an id, name and sortOrder. Use ?sort=sortOrder on a supported status collection to display pipeline order, and follow pagination links for further results.
| Read operation | What it returns |
|---|---|
| Search custom statuses | Statuses accessible to your application |
| Read a custom status | One status by ID |
| Read a deal's current custom status | Its status resource |
| Read a deal's status identifier | Its status linkage |
| Read an organisation's statuses | Pipeline stages for that organisation |
| Read an organisation's status identifiers | Status linkage without the attributes |
To find the deal's organisation, read its adviser, then that adviser's organisation. These reads need their applicable scopes and record access.
You can also request GET /jsonapi/deals/5001?include=customStatus and resolve the current status from included using relationships.customStatus.data.
Change a deal's status
Use change a deal's custom status with api.deals.update or a broader applicable scope. The target must be an active custom status belonging to the deal's organisation. Supply its ID, rather than its name or the general dealStatus value.
This operation uses plain JSON, with application/json for both headers and no data wrapper:
PUT {API_BASE_URL}/jsonapi/deals/5001/status
Authorization: Bearer {ACCESS_TOKEN}
UserId: {ADVISER_CONTACT_ID}
Accept: application/json
Content-Type: application/json
{ "customStatusId": 8001 }
A successful request returns 200 OK, including when the deal is already at the requested status. An illustrative response is:
{
"id": 5001,
"customStatusId": 8001,
"statusName": "Submitted to lender"
}
Allowed movements depend on the underlying stage, not the custom status name or its sort order:
| Current stage | Allowed target stages |
|---|---|
| Pre-submission | Any supported stage |
| Submitted, including approvals and pending settlement | Submitted, settled, post-settlement, cancelled |
| Settled | Settled, post-settlement |
| Post-settlement, including varied and repaid | Post-settlement |
| Cancelled / not proceeding | Cancelled / not proceeding |
Once submitted, a deal cannot return to pre-submission. Settled and post-settlement deals cannot be cancelled. Invalid targets or movements return 400; a missing or inaccessible deal returns 404. Inspect the response's errors array for details.
Asset and commercial finance
Diversified deals use separate resource types and read endpoints. See asset finance deals, asset finance referrals and commercial finance deals for summary fields, access scopes, filters, and person and business applicant relationships. Residential participant, structure and write operations do not automatically apply to those resources.
Notes and external references
A new deal note links to an existing deal through relationships.deal.data. Include the deal resource type and ID, and provide permitted adviser context for the write. External references help associate records with another system; they are not a duplicate-prevention guarantee.
See the sample client for a create-and-update note example.
Follow the external-reference walkthrough to link a deal to your system’s opportunity ID, find it again, and maintain the mapping.