Family Linking
The Leads Management module automatically links applicants who belong to the same family. This is primarily achieved through the parents table, which deduplicates parent/guardian records by email address within each school.
How Family Linking Works
The system uses a three-layer data model to track family relationships:
- Parents table -- stores one record per parent/guardian, deduplicated by email within each school.
- Families table -- represents a family unit.
- Family Members table -- a junction table that links parents and children (leads) to families, with a role field (e.g., mother, father, guardian).
Automatic Linking via Form Submissions
When a parent submits an application form for a child:
- The system checks if a parent record already exists with the submitted email address for that school.
- If found, the existing parent record is reused (not duplicated).
- A new family is created (or an existing one is used) and the child is linked as a family member.
- Because the same parent appears in multiple families, the system can identify siblings.
TIP
This means that if a parent submits applications for two children, the system automatically recognizes them as siblings because they share the same parent email address -- no manual linking required.
Viewing Family Connections
On an applicant's detail page, you can see their family connections:
- Parents/Guardians -- listed with their name, email, phone, relationship role, and other contact details.
- Siblings -- other children linked to the same family through shared parents.
- Family role -- each family member has a role such as child, mother, father, guardian, step_mother, step_father, or other.
Family Detection Rules
The Family Detection Service scans your database for potential family groups using configurable rules:
| Rule | How It Works |
|---|---|
| Parent Email | Groups leads that share a parent record with the same email address. This is the most reliable method and the default. |
| Child Name + DOB | Identifies leads where the child's name and date of birth are identical (catches re-submissions). |
| Child Name Only | Matches on child name alone. Less precise but catches cases where DOB might differ slightly. |
| Parent Name + Phone | Matches families where the parent's full name and phone number are identical. |
| Parent Name + Address | Matches families where the parent's full name and address match. |
How Detection Differs from Linking
- Family Linking is the automatic creation of parent-child relationships in the database when forms are submitted. It is real-time and always active.
- Family Detection is a scan that identifies potential family groups that may not yet be linked. It finds patterns across your data and suggests connections.
Parent Deduplication
The ParentService::findOrCreate() method ensures parent records are not duplicated:
- When a form is submitted, the service searches for an existing parent with the given email within the school.
- If a match is found, the existing parent record is used and updated with any new information.
- If no match is found, a new parent record is created.
This deduplication ensures that even if a parent submits multiple forms, only one parent record exists per email address per school.
Orphan Lead Detection
The system also identifies "orphan leads" -- applicants that were created without proper family linking (e.g., from imports or older data). It detects:
- Leads without any family record that share a parent email with an existing family.
- These orphans are flagged for review and can be linked to their families.
WARNING
Orphan leads typically arise from data imported before the family linking system was implemented, or from manual lead creation where parent details were entered but not properly linked. The family detection scan identifies these cases for cleanup.
Managing Family Records
Viewing All Family Members
On the applicant detail page, the family section shows:
- All parents/guardians linked to the family, with their role and contact details.
- All children (leads) linked through the same family.
- Links to navigate directly to sibling applicant records.
Parent Address Data
Parent records store address information (address, city, country) that is shared across all children in the family. When a parent updates their address via a form submission, the change is reflected for all linked children.
TIP
The system preserves the original parent addresses from the parents table. Historical form submission data (including guardian details entered on forms) is kept in the lead's data JSON field as a read-only archive.