Regions

Endpoints for managing regions and organizing geographical territories within RoofLink. Regions represent service areas or geographical territories used to organize operations, assign employees, and manage company resources across different locations.

Supported Region Operations

This category includes the following operations:

Querying Regions

• List Regions: Retrieve a paginated list of all regions for your company with optional text search filtering by region name.
• Retrieve Region: Get detailed information for a specific region including contact details, DBA information, office manager details, supplier configurations, and computed fields.

Creating and Managing Regions

• Create Region: Create a new region with contact information, timezone settings, DBA details, and overhead configuration. The color field is auto-generated if not provided.
• Update Region: Update all details of an existing region including contact information, timezone, DBA settings, office manager assignment, and supplier ship-to configurations.
• Delete Region: Permanently delete a region from the system. This operation is restricted to admin employees only.

Region Status Management

• Activate Region: Activate a single region by setting its is_active status to true, making it available for operations.
• Deactivate Region: Deactivate a single region by setting its is_active status to false, removing it from active operations while preserving data.
• Bulk Activate Regions: Activate multiple regions in a single operation for efficient batch status management.
• Bulk Deactivate Regions: Deactivate multiple regions in a single operation for efficient batch status management.

Region Features

Contact and Location Information

Regions store comprehensive contact and location details:

• Contact Details: Phone numbers and email addresses for regional communications
• Physical Address: Street address with optional city, state, and ZIP code fields
• Full Address: Automatically computed field combining all address components for display purposes
• Geographic Coordinates: Latitude and longitude values for mapping and location services (both required together)

DBA (Doing Business As) Configuration

Regions support DBA information for companies operating under different names:

• DBA Name: Alternative business name for the region
• DBA Abbreviation: Short form of the DBA name
• DBA URLs: Website, Better Business Bureau profile, Facebook page, and Yelp listing URLs
• Legal Information: Law suits county and right of rescission days (default: 3 days)

Timezone Management

Each region has its own timezone setting for scheduling and time-based operations. Supported timezones include:

• US/Central (default)
• US/Eastern
• US/Mountain
• MST
• US/Pacific
• US/Alaska
• US/Hawaii

Office Manager Assignment

Regions can be assigned an office manager from the company's employee roster:

• Office manager must be an active employee in the same company
• The detail endpoint returns complete office manager information including name, email, and color code
• Office manager assignment is optional and nullable

Overhead Configuration

Regions can define job overhead percentages:

• Job Overhead: Decimal percentage value (e.g., 5.5 for 5.5%)
• Default value: 0
• Additional to company-level job overhead
• Used in job cost calculations and pricing

Active Status Control

Regions can be activated or deactivated:

• Active Regions: Available for normal operations, visible in selection lists
• Inactive Regions: Hidden from active operations but data is preserved
• Use single or bulk activation/deactivation endpoints for status management
• All status actions return a simple "ok" response on success

Color Coding

Each region has a color code for visual identification:

• Hex color format (e.g., "#3498DB")
• Maximum length: 12 characters
• Automatically generated using a random color if not provided during creation
• Used in UI elements for quick region identification

Filtering and Search

The List Regions endpoint provides search capabilities:

• Search Parameter: Case-insensitive substring search on region names
• Results are paginated with configurable page size
• Only regions from the authenticated user's company are returned

Permissions and Access Control

Permission Levels

Region operations have different permission requirements:

• Read Operations (GET): Available to all authenticated employees in the company
• Write Operations (POST, PUT, DELETE): Restricted to admin employees only
  • Non-admin employees receive a 403 Forbidden response
  • Status management endpoints (activate/deactivate) also require admin permissions

Important Notes

Labor Warranty

Regions can specify a labor warranty period in years (default: 5 years). This setting affects warranty calculations for jobs within the region.

Abbreviation Usage

Region abbreviations (abbr field) are used throughout the system for compact displays and internal references. Choose meaningful, unique abbreviations for each region.

Overhead Calculations

The region's job overhead percentage is additional to any company-level overhead. Total job overhead is calculated by combining both values.

Related Operations

• List Employees: View employees that can be assigned as office managers
• Get Employee Details: View complete employee information for office manager assignment