Client Associations & Relationships

Client Associations & Relationships

Client associations let you link individual clients to company clients (and vice versa) to build a complete picture of your business relationships. An individual can be associated with multiple companies, and a company can have many associated individuals — all tracked through a many-to-many pivot table.

What are client associations?

An association is a link between an individual client and a company client stored in the client_associations pivot table. Each association record is a ClientAssociation model with the following fields:

• individual_client_id — The UUID of the individual client in the association
• company_client_id — The UUID of the company client in the association
• role — The individual's role at the company (see role options below)
• notes — Optional free-text notes about the relationship (e.g. "Main point of contact for AV enquiries")
• is_primary — Boolean flag indicating whether this is the individual's primary company. Only one association per individual should be marked as primary.
• created_by — The user who created the association

Available roles

The ROLE_OPTIONS constant on the ClientAssociation model defines the available role values:

• Director
• Owner
• Manager
• Employee
• Freelancer
• Contractor
• Contact
• Representative
• Other

These roles appear in a dropdown when creating or editing an association. Choose the value that best describes the individual's relationship to the company.

Relationships on the Client model

The Client model provides three methods for navigating associations:

• associatedCompanies() — For individual clients. Returns all company clients that this individual is linked to, with pivot data (role, notes, is_primary, created_by).
• associatedIndividuals() — For company clients. Returns all individual clients linked to this company, with the same pivot data.
• getPrimaryCompany() — For individual clients. Returns the single company marked as primary (is_primary = true), or null if no primary company is set.

Display on the detail page

Associations appear in the Client Associations section on the client detail page's Overview tab. The display varies by client type:

• For individual clients — Shows a list of linked companies. Each entry displays the company name, the individual's role at that company as a coloured badge, and a primary indicator if applicable. Clicking a company name navigates to that company's detail page.
• For company clients — Shows a list of linked individuals. Each entry displays the individual's name, their role badge, and whether they are marked as primary. Clicking an individual's name navigates to their detail page.

Associations on the create and edit form

The ClientAssociations component appears in the sidebar of the client edit form (not the create form, since the client must be saved first). From this panel you can add, edit, and remove associations without leaving the form.

Use cases

Associations solve several common business relationship challenges:

• Track representatives — Record which individuals represent which companies, so your team always knows who to contact for a given organisation.
• Multiple company affiliations — One individual can work for or represent several companies. For example, a freelance production manager may represent three different event companies. Each association has its own role and notes.
• Company staff directory — A company record shows all associated individuals with their roles, giving you a quick staff directory for that organisation.
• Primary company identification — The is_primary flag on an individual's association identifies their main company, useful when an individual works with multiple organisations but one is their primary employer.

Managing associations

Adding an association

1. Open the client detail page for either the individual or the company.
2. Navigate to the Overview tab and locate the Client Associations section.
3. Click Add Association.
4. Search for and select the client to link (individuals when viewing a company, or companies when viewing an individual).
5. Choose a role from the dropdown.
6. Optionally add notes describing the relationship.
7. Set the is_primary toggle if this is the individual's main company.
8. Click Save.

Editing an association

Click the edit icon next to any association to change the role, notes, or is_primary flag. The linked client itself cannot be changed — remove the association and create a new one instead.

Removing an association

Click the delete icon next to an association and confirm the removal. This deletes the pivot record only; neither the individual nor the company client is affected. Historical project and invoice data remains intact.

Benefits

• Quick navigation — Jump between related client records with a single click from the Associations section.
• Full relationship picture — See all of an individual's company affiliations or all of a company's associated staff at a glance.
• Linked contact information — Access phone numbers, emails, and addresses for associated clients without searching separately.
• Audit trail — Each association records who created it and when, providing a clear history of relationship changes.

Tips

• Always set the is_primary flag for individuals who have a single main employer — this makes it easy to identify their primary affiliation in list views.
• Use the notes field to record specifics such as "Handles all AV bookings" or "Authorised to approve quotes up to £5,000".
• When a staff member leaves a company, update or remove the association rather than deleting the individual client record. The individual may still be an active client in their own right.
• Review company associations periodically to ensure roles are still accurate, especially after organisational changes at your client's business.
• Associations work alongside client contacts — use associations for cross-client relationships and contacts for people within a single client record.