Skip to main content

Contact parent hierarchy

Summary​

Contacts now support an optional parentContact reference so practices can group contract-level contacts (for example BUPA Gold) under a root contact (for example BUPA) while keeping patient insurer relationships unchanged.

parentContact is part of the BILLING_RULES feature. Practices must have the BILLING_RULES feature flag enabled before createContact or updateContact will accept writes to this field. Other contact fields remain available without the flag, and parentContact is still returned on reads when set.

API changes​

  • createContact accepts optional parentContact: ID when the practice has the BILLING_RULES feature flag.
  • updateContact(contactData:) accepts optional parentContact: ID when the practice has the BILLING_RULES feature flag.
  • Contact exposes parentContact: ID on reads.

To clear an existing parent and return a child contact to root level, pass parentContact: null in updateContact.

Validation behaviour​

When BILLING_RULES is enabled and parentContact is set, the API validates that the target:

  • is an active Contact,
  • belongs to the same practice,
  • is not the same contact (no self-reference),
  • does not create a cycle,
  • is a root contact (single-level hierarchy in v1).

Deleting a root contact with active children is blocked until children are unlinked or reassigned.

Patient relationships​

Patient relatedAccounts are unchanged. Updating contact parent hierarchy does not modify existing patient insurer relationship data.