Deals and their related records
A deal connects client information with a business opportunity or application workflow. Its related records can include contacts, participants, notes, structures 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 and their personal/contact details. | You need to know who is linked to the deal or retrieve their email addresses. |
participants | The deal-specific participation records, their role flags and their links to a contact and deal. | 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 flags 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. The role flags can be null, so handle an unspecified value separately from an explicit false. Also handle an empty contact relationship instead of assuming every participant has a returned contact.
The participant endpoints are read-only. Manage participant roles in MyCRM; updating a contact's name or email does not change their role in a deal.
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.
Statuses and reference data
A system status and an organisation's custom pipeline status represent different concepts. Keep their identifiers and context when building reports or mapping workflow states. Do not assume labels are globally unique or immutable.
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 general 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.