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