Contact Management

Contacts are central to OptiFlow, representing customers, suppliers, and other business relationships. Proper contact management ensures smooth invoicing, quotations, and reporting.

Overview

Contact management features:

Unified customer and supplier database
Multiple contact types (customer, supplier, both)
Contact relationships (family members, business partners)
Comprehensive contact information (addresses, IDs, phones, emails)
Activity history (invoices, quotations, payments)
Bulk import from Excel/CSV
Duplicate detection

Contact Types

OptiFlow supports different contact classifications:

Type	Code	Usage
Customer	`customer`	Entities you sell to
Supplier	`supplier`	Entities you buy from
Both	`both`	Entities you both buy from and sell to

Reference: ContactType enum in app/Enums/ContactType.php

Creating a Contact

Navigate to Contacts

Go to Contacts → Create ContactReference: ContactController::create() in app/Http/Controllers/ContactController.php:42Requires contacts:create permission.

Enter Basic Information

Required Fields:

Name: Contact’s full name or business name
Contact Type: Customer, Supplier, or Both

Optional Fields:

Commercial Name: Trading name (if different from legal name)
Email: Primary email address
Phone: Primary phone number
Mobile: Mobile phone number
Website: Company website

// Available contact types loaded in the form
'contact_types' => collect(ContactType::cases())
    ->map(fn ($type) => [
        'value' => $type->value,
        'label' => $type->label(),
    ]);

Add Identification

Configure identification documents:Identification Type: Select from:

RNC (Registro Nacional de Contribuyentes) - Tax ID
Cédula - National ID card
Pasaporte - Passport
Other identification types

Identification Number: Enter the ID number

For Dominican Republic businesses, RNC is mandatory for proper tax compliance and invoice generation.

Reference: IdentificationType enum defines available ID types

'identification_types' => collect(IdentificationType::cases())
    ->map(fn ($type) => [
        'value' => $type->value,
        'label' => $type->label(),
    ]);

Add Address Information

Primary Address (Optional but recommended):

Street address
City
State/Province
Postal code
Country

The primary address is used for:

Invoice billing address
Delivery address (default)
Correspondence

You can add multiple addresses per contact. The first address created becomes the primary address.

Configure Relationships

Link this contact to related contacts:Use Cases:

Family members (parent, child, spouse)
Business partners
Subsidiaries
Alternative contacts

To Add Relationship:

Search for existing contact
Select relationship type or add description
Add to relationships list

Benefits:

View consolidated activity across related contacts
Track family/group purchasing patterns
Share notes and history

Reference: Contact relationships are many-to-many with descriptions

// From ContactController::show()
$contactIds = $contact->relatedContactIdsWithSelf();

// Invoices query includes related contacts
$invoices = Invoice::query()
    ->whereIn('contact_id', $contactIds)
    ->get();

Save Contact

Click Create ContactThe system:

Validates required fields
Checks for potential duplicates (optional)
Creates contact record
Creates primary address (if provided)
Establishes relationships
Redirects to contact detail page

Reference: CreateContactAction::handle() in app/Actions/CreateContactAction.php

Contact Information Fields

Complete Field List

Identity:

Name (required)
Commercial name
Identification type
Identification number

Communication:

Email
Phone
Mobile
Website

Classification:

Contact type (Customer/Supplier/Both)
Tags or categories (if configured)

Address:

Multiple addresses supported
Primary address designation
Full address components

Relationships:

Related contacts with descriptions
Bidirectional relationships

Financial:

Credit limit (optional)
Payment terms preference
Tax classification

Viewing Contact Details

Navigate to Contact

Go to Contacts → Select a contact from the listReference: ContactController::show() in app/Http/Controllers/ContactController.php:82

Overview Tab

View contact summary:

Basic information
Primary address
Recent activity
Quick statistics

Statistics Shown:

$stats = [
    'total_invoices' => (clone $invoiceQuery)->count(),
    'total_quotations' => (clone $quotationQuery)->count(),
    'total_invoiced' => (clone $invoiceQuery)->sum('total_amount'),
    'total_paid' => /* sum of payments */,
    'pending_amount' => /* outstanding balance */,
];

Invoices Tab

View all invoices for this contact:

Invoice number and date
Total amount
Status (Paid, Pending, Overdue)
Payment status
Quick actions (view, download PDF)

Limited to 10 most recent, with link to see all.

Quotations Tab

View all quotations:

Quotation number and date
Status (Pending, Approved, Converted)
Total quoted amount
Actions (view, convert to invoice)

Activity Tab

Complete activity log:

Contact changes
Invoice created/paid
Quotations sent
Payments received
Notes added
User who performed action
Timestamp

Comments Tab

Internal notes and comments:

Add notes about the contact
Communication history
Special instructions
Threaded discussions

Reference: Contact implements Commentable interface using HasComments trait

Editing Contacts

Open Contact Editor

From contact detail page, click Edit ContactReference: ContactController::edit() in app/Http/Controllers/ContactController.php:170Requires contacts:edit permission.

Modify Information

Update any contact fields:

Basic information
Contact type
Identification
Addresses
Relationships

Changing a contact’s identification number may affect tax reporting and compliance. Ensure the change is legitimate and properly documented.

Save Changes

Click Update ContactChanges are tracked in the activity log with:

Fields changed
Old and new values
User who made the change
Timestamp

Reference: UpdateContactAction::handle()

Contact Relationships

Setting Up Relationships

Contact relationships allow linking related individuals or businesses: Relationship Types (custom descriptions):

“Parent” / “Child”
“Spouse”
“Business Partner”
“Subsidiary”
“Primary Contact” / “Alternative Contact”
“Referral Source”

Benefits of Relationships

Consolidated Reporting: View all invoices and quotations for a family or group
Shared History: See complete interaction history
Cross-References: Easy navigation between related contacts

Adding Relationships

Edit Contact

Navigate to contact and click Edit

Search for Related Contact

Use the relationship search field:

Type contact name or ID
Select from results
Contact cannot be related to itself

// Search excludes the current contact
$contactSearch->searchActive(
    (string) $request->string('relationship_search'),
    $contact->id  // Exclude this contact from results
);

Add Description

Describe the relationship:

“Mother of [contact]”
“Alternative phone for [contact]”
“Partner”

Save

Relationship is bidirectional - appears on both contacts

Importing Contacts

Bulk import contacts from Excel or CSV files.

Navigate to Import

Go to Contacts → Import ContactsReference: ContactImportController in app/Http/Controllers/ContactImportController.php

Upload File

Supported formats:

Excel (.xlsx, .xls)
CSV (.csv)

Requirements:

First row should contain headers
At minimum, include contact names

Reference: CreateContactImportAction parses file using ParseExcelFileAction or ParseCsvFileAction

Map Columns

Map your file columns to OptiFlow contact fields:Your File Column → OptiFlow Field

“Customer Name” → Name
“Tax ID” → Identification Number
“Email Address” → Email
etc.

Available fields from ContactImport::getAvailableFields():

name
commercial_name
email
phone
mobile
identification_type
identification_number
contact_type
address
city
state
postal_code
country

// Preview data shown for verification
'previewData' => array_slice($contactImport->import_data ?? [], 0, 5)

Validate Data

Review validation results:

✅ Valid rows (will be imported)
⚠️ Warnings (will import with caution)
❌ Errors (will be skipped)

Common issues:

Missing required fields (name)
Invalid email formats
Duplicate identification numbers

Reference: ValidateContactImportDataAction

Process Import

Click Import ContactsSystem processes:

Validates each row
Checks for duplicates
Creates contact records
Creates addresses
Generates import summary

Reference: ProcessContactImportAction::handle()

Review Results

Import summary shows:

Total rows processed
Successfully imported
Skipped (with reasons)
Duplicates detected
Link to imported contacts

Duplicate Detection

When importing, the system checks for duplicates based on:

Identification number (if provided)
Email address
Exact name match

Duplicate handling options:

Skip duplicates
Update existing contacts
Create anyway (with warning)

Reference: CheckContactDuplicatesController provides duplicate checking

Contact Search

Efficient contact search throughout OptiFlow:

Search Locations

Contact List Page: Full-text search with filters
Invoice/Quotation Creation: Customer search dropdown
Quick Search: Global search bar

Search Criteria

Contacts can be found by:

Name (partial match)
Commercial name
Identification number
Email
Phone number

// ContactSearch::searchCustomers() implementation
public function searchCustomers(string $query): array
{
    return Contact::query()
        ->where(function ($q) use ($query) {
            $q->where('name', 'like', "%{$query}%")
              ->orWhere('identification_number', 'like', "%{$query}%")
              ->orWhere('email', 'like', "%{$query}%")
              ->orWhere('phone', 'like', "%{$query}%");
        })
        ->whereIn('type', ['customer', 'both'])
        ->limit(20)
        ->get()
        ->map(fn ($contact) => $this->toOption($contact))
        ->toArray();
}

On contact list page:

Contact type (Customer/Supplier/Both)
Active/Inactive status
Tags or categories
Date created

Deleting Contacts

Navigate to Contact

Open the contact you want to delete

Click Delete

Click Delete Contact buttonReference: ContactController::destroy() - requires contacts:delete permission

Confirm Deletion

System checks if contact can be deleted:Cannot delete if:

Contact has invoices
Contact has quotations
Contact has payments
Contact has other related records

Solution for contacts with records:

Mark as inactive instead of deleting
Or remove as a “soft delete” (if configured)

Reference: DeleteContactAction::handle()

Deleting contacts is permanent and cannot be undone. For contacts with transaction history, consider marking them as inactive instead.

Best Practices

Complete Contact Information: Fill in as much information as possible. Complete contact records improve reporting and customer service.

Use Relationships: Link family members and related businesses to track group purchasing and provide better service.

Regular Cleanup: Periodically review and merge duplicate contacts, update outdated information.

Categorize Contacts: Use consistent contact types and tags for better segmentation and reporting.

Document Interactions: Use comments to record important customer conversations, preferences, and special instructions.

Common Scenarios

Scenario: Family Group Management

Situation: Optometry clinic with family patients

Create Primary Contact

Create contact for head of household

Create Family Members

Create individual contacts for spouse and children

Link Relationships

Add relationships:

Spouse relationship
Parent-child relationships

View Consolidated

From any family member, view complete family history of invoices and quotations

Scenario: Corporate Account

Situation: Business with multiple departments or contacts

Create Company Contact

Main business entity with RNC

Create Department Contacts

Individual contacts for departments (if needed)

Link as Subsidiaries

Relationship: “Department of [Company]“

Troubleshooting

Cannot Create Contact - Duplicate Error

Problem: “A contact with this identification number already exists” Solution:

Search for existing contact
Update existing contact instead
Or use different identification type if legitimately different entity

Contact Not Appearing in Search

Problem: Contact exists but doesn’t show in invoice customer search Cause: Contact type is set to “Supplier” only Solution:

Edit the contact
Change type to “Customer” or “Both”

Problem: Invoice was created but doesn’t appear on contact detail page Investigation:

Check if invoice was created for a related contact instead
Verify invoice is in the current workspace

Get Started

Core Features

Guides

Workflows & Automation

Contact Management

Overview

Contact Types

Creating a Contact

Contact Information Fields

Complete Field List

Viewing Contact Details

Editing Contacts

Contact Relationships

Setting Up Relationships

Benefits of Relationships

Adding Relationships

Importing Contacts

Duplicate Detection

Contact Search

Search Locations

Search Criteria

Search Filters

Deleting Contacts

Best Practices

Common Scenarios

Scenario: Family Group Management

Scenario: Corporate Account

Troubleshooting

Cannot Create Contact - Duplicate Error

Contact Not Appearing in Search

Build docs developers (and LLMs) love

Get Started

Core Features

Guides

Workflows & Automation

Documentation Index

​Overview

​Contact Types

​Creating a Contact

​Contact Information Fields

​Complete Field List

​Viewing Contact Details

​Editing Contacts

​Contact Relationships

​Setting Up Relationships

​Benefits of Relationships

​Adding Relationships

​Importing Contacts

​Duplicate Detection

​Contact Search

​Search Locations

​Search Criteria

​Search Filters

​Deleting Contacts

​Best Practices

​Common Scenarios

​Scenario: Family Group Management

​Scenario: Corporate Account

​Troubleshooting

​Cannot Create Contact - Duplicate Error

​Contact Not Appearing in Search

​Related Invoices Not Showing

​Related Features

Build docs developers (and LLMs) love

Overview

Contact Types

Creating a Contact

Contact Information Fields

Complete Field List

Viewing Contact Details

Editing Contacts

Contact Relationships

Setting Up Relationships

Benefits of Relationships

Adding Relationships

Importing Contacts

Duplicate Detection

Contact Search

Search Locations

Search Criteria

Search Filters

Deleting Contacts

Best Practices

Common Scenarios

Scenario: Family Group Management

Scenario: Corporate Account

Troubleshooting

Cannot Create Contact - Duplicate Error

Contact Not Appearing in Search

Related Invoices Not Showing

Related Features