> ## Documentation Index
> Fetch the complete documentation index at: https://docs.penbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Contacts
> The people involved in a case
Contacts are the people involved in a case. Every case has a **Main Contact** — the primary individual the case is about. Cases can also have **Secondary Contacts** — additional stakeholders like brokers, experts, partners, or opposing parties.
Each contact is identified with a unique key when defining the case, which allows the system to reference them in steps, notifications, and data throughout the platform.
## Main Contact
The main contact is the primary individual a case is about and the primary recipient for all external communications.
**Every case requires a main contact.** The main contact:
* Receives forms sent from the case
* Receives email communications and notifications
* Is the primary point of contact for the matter
* Can be an individual person or organization representative
* Must have at least an email address or phone number to receive communications
A case without a main contact cannot send forms or communications to external parties. Always add a main contact to enable full case functionality.
**Main contact information:**
* **Name** - Full name of the individual
* **Email** - Primary email address (required for email communications)
* **Phone** - Phone number (required for SMS communications)
* **Language** - Preferred communication language
* **Organization** - Optional company or organization name
* **Additional fields** - Custom fields based on your workspace configuration
When a case is created from a form submission or incoming email, the sender's information is automatically added as the main contact.
## Secondary Contacts
Secondary contacts are additional stakeholders involved in the case beyond the main contact. These can include:
**Common secondary contact roles:**
* **Brokers** - Insurance brokers, real estate agents, financial advisors
* **Experts** - Technical experts, appraisers, medical professionals
* **Partners** - Business partners, co-applicants, joint account holders
* **Legal representatives** - Lawyers, guardians, trustees
* **Billing contacts** - Separate contact for invoicing and payments
* **Technical contacts** - IT contacts, system administrators
* **Opposing parties** - In legal or dispute cases
Each secondary contact can have a specific role that defines their involvement in the case.
**Secondary contact configuration:**
* **Role** - Defines the contact's relationship to the case
* **Key** - Unique identifier for referencing in steps and automations
* **Contact information** - Same fields as main contact
* **Permissions** - What they can see or do (if applicable)
Use secondary contacts to involve multiple stakeholders in a case while maintaining clear roles and responsibilities.
## Contact Keys
Each contact (main and secondary) is identified with a unique key when defining the case. This key system allows the platform to reference contacts in various contexts:
**Where contact keys are used:**
* **Steps** - Reference which contact receives an email or form
* **Notifications** - Specify who gets notified about case events
* **Data fields** - Reference contact information in case data
* **Email templates** - Insert contact details dynamically
* **Automations** - Trigger actions based on contact responses
**Key naming:**
* Main contact typically uses the key `main`
* Secondary contacts use descriptive keys like `broker`, `expert`, `partner`, `billing`
* Keys must be unique within a case
* Keys are defined in case templates or when adding contacts to individual cases
Contact keys are explained conceptually here. For the technical notation and variable syntax, see the penscript documentation.
## Assigning Contacts
Contacts can be assigned to a case in several ways:
### Select Existing Contact
Choose from contacts already in your workspace:
* Search by name, email, or organization
* View contact history and previous cases
* Ensures data consistency across cases
* Maintains single source of truth for contact information
### Create New Contact
Add a new contact directly when creating or updating a case:
* Enter contact information manually
* Contact is added to workspace contact database
* Available for future cases
* Can be updated centrally
### Automatic Assignment
Contacts are automatically assigned in certain scenarios:
* **From form submission** - Form respondent becomes main contact
* **From incoming email** - Email sender becomes main contact
* **Via API** - Contact information provided in API request
### Bulk Import
For campaigns or large case imports:
* Upload CSV file with contact information
* Map columns to contact fields
* Create multiple cases with pre-assigned contacts
* Useful for annual updates or mass communications
## Language Preferences
Each contact can have a preferred communication language. This affects:
**Form language:**
* Forms sent to the contact appear in their preferred language
* Form templates must have translations available
* Automatic language selection based on contact preference
**Email language:**
* Email templates can have multiple language versions
* System selects appropriate version based on contact language
* Ensures professional communication in contact's language
**Supported languages depend on your workspace configuration.**
Set contact language preferences early to ensure all communications are sent in the correct language from the start.
## How Contact Information Flows
Contact information flows through the platform in several ways:
### In Steps
When sending forms or emails:
* Select which contact receives the communication
* Contact's email or phone is automatically used
* No need to re-enter contact information
* Changes to contact details automatically reflect in future communications
### In Data Fields
Case data can reference contact information:
* Pull contact name into document templates
* Use contact email for automated notifications
* Reference contact organization in reports
* Maintain consistency across all case materials
### In Notifications
Automations can notify specific contacts:
* Send confirmation emails to secondary contacts
* Notify brokers when status changes
* Alert partners when documents are signed
* Configure per contact role
### In Reports
Contact information appears in case reports:
* Filter cases by contact
* View all cases for a specific contact
* Track contact interactions across cases
* Analyze contact engagement
## Managing Contacts
**Updating contact information:**
* Changes to workspace contacts affect all future communications
* Existing case timeline preserves original contact info (audit trail)
* Update in one place, applies to new interactions
**Removing contacts:**
* Secondary contacts can be removed from cases
* Main contact cannot be removed (case requirement)
* Removed contacts remain in timeline history
**Contact privacy:**
* Contact information is stored securely
* Access controlled by workspace permissions
* Complies with data protection requirements
* Can be anonymized or deleted per retention policies
***
## Next Steps
Learn about cases and main contacts
Send communications to contacts
Reference contact information in data
Define contact roles in templates