Bulk Rating¶

The Bulk Rating System allows you to process hundreds or thousands of insurance premium calculations simultaneously through CSV upload or API integration. This is ideal for portfolio analysis, renewal processing, or mass quoting.

Overview ¶

What is Bulk Rating?¶

Bulk Rating enables you to:

Process 100s to 1000s of quotes in a single batch
Upload rating requests via CSV file
Submit via REST API for system integration
Monitor real-time progress
Download comprehensive results
Receive webhook notifications when complete

Key Features ¶

Bulk Rating Features¶
Feature	Description
High Volume Processing	Handle 1000s of ratings per job
CSV Upload	Simple spreadsheet-based submission
API Integration	Programmatic submission and retrieval
Real-Time Progress	Live updates as ratings complete
Error Handling	Detailed error logs for failed ratings
Webhook Notifications	Get notified when jobs finish
Result Export	Download results in CSV or JSON
Performance Optimized	Cached data for faster processing

When to Use Bulk Rating ¶

Use bulk rating for:

Portfolio Renewals: Rate entire portfolio at renewal
Market Analysis: Compare pricing across segments
Data Migration: Import historical ratings
Batch Quoting: Process overnight quote requests
System Integration: Connect to policy management systems
Testing: Validate product configurations at scale

Getting Started ¶

Accessing Bulk Rating ¶

Access bulk rating:

Click Bulk Rating in main menu
Choose your method: * Upload CSV - File-based submission * API Submit - Programmatic submission * View Jobs - Monitor and download results

Permissions Required ¶

Warning

Bulk rating is a powerful feature. Only users with Product Manager or Administrator roles can access it.

Using CSV Upload ¶

Step 1: Prepare Your CSV File ¶

Download the CSV template:

Navigate to Bulk Rating → Upload
Click Download Template
Choose product (e.g., “BOP Template”)
Open in Excel or Google Sheets

CSV Format ¶

Required columns:

product_code,effective_date,external_reference,territory,class_code,...

Example BOP template:

BOP Rating Template¶
product_code	effective_date	external_reference	territory	class_code	building_value	building_class
BOP	2025-01-01	POL-001	01	43211	500000	B
BOP	2025-01-01	POL-002	14	47221	750000	A
BOP	2025-01-01	POL-003	02	43211	1000000	B

Coverage columns (add for each coverage):

coverage_1_code,coverage_1_limit,coverage_1_deductible
coverage_2_code,coverage_2_limit,coverage_2_deductible

Example with coverages:

BOP with Coverages¶
product_code	territory	building_value	cov_1_code	cov_1_limit	cov_1_deductible
BOP	01	500000	BLDG	500000	1000
BOP	14	750000	BLDG	750000	5000

Step 2: Fill In Your Data ¶

CSV Data Entry — *Screenshot Placeholder: Excel showing filled CSV with multiple rows of rating data*¶

Data entry tips:

One row per rating: Each row is one premium calculation
Required fields: Must be filled (marked in template)
Optional fields: Can be left blank
Consistent format: Dates as YYYY-MM-DD, numbers without commas
External reference: Your own tracking number
No formulas: Enter values directly, not Excel formulas

Common data types:

CSV Data Types¶
Field Type	Format	Example
Product Code	Text	BOP, GL_POLICY, WC
Date	YYYY-MM-DD	2025-01-17
Currency	Number (no $, no ,)	500000 (not $500,000)
Percentage	Decimal	0.15 (not 15%)
Territory	Text/Number	01, 14, NY
Yes/No	true/false or 1/0	true, false, 1, 0

Step 3: Upload Your File ¶

CSV Upload Interface — *Screenshot Placeholder: Upload form with drag-drop area, file selector, optional fields for job name and webhook URL*¶

Upload your CSV:

Go to Bulk Rating → Upload
Drag-and-drop CSV file or click Choose File
Optional: Enter job name (e.g., “Q1 2025 Renewals”)
Optional: Add webhook URL for notifications
Click Upload and Process

Upload validation:

✓ File uploaded: renewals_q1.csv
✓ Size: 2.4 MB
✓ Detected: 1,247 rating requests
✓ Product: BOP
✓ Format: Valid

Processing started...
Job ID: JOB-2025-01-17-001

Step 4: Monitor Progress ¶

Job Progress Monitoring — *Screenshot Placeholder: Progress page showing real-time updates - progress bar, statistics (1247 total, 856 completed, 823 success, 33 errors), estimated time remaining*¶

After upload, monitor progress:

Progress Bar: Visual completion percentage
Statistics: Total, completed, success, errors
Status: Queued → Processing → Completed
Estimated Time: Time remaining
Error Count: Failed ratings (click to view details)
Auto-Refresh: Page updates every 5 seconds

Example progress display:

Job: Q1 2025 Renewals
Status: Processing
Progress: 856 of 1,247 (68.6%)

Statistics:
├── Total requests: 1,247
├── Completed: 856
├── Success: 823
└── Errors: 33

Estimated time remaining: 2 minutes

[████████████████████░░░░░░░░░░] 68.6%

Step 5: Download Results ¶

When complete, download results:

Job status changes to “Completed”
Download options appear: * Download CSV: Results in spreadsheet format * Download JSON: Results in JSON format * Download Error Log: Details of failed ratings * View Summary: Quick statistics view

Result CSV format:

Results CSV¶
external_reference	status	total_premium	coverage_1_premium	coverage_2_premium	errors
POL-001	success	2340.00	1200.00	1140.00
POL-002	success	2847.00	1320.00	1527.00
POL-003	error				Invalid territory code

Using the API ¶

API Overview ¶

Bulk API Flow — *Screenshot Placeholder: Flow diagram showing Submit Job → Poll Status → Download Results with API endpoints*¶

API workflow:

Submit Job: POST bulk rating requests
Get Job Status: Poll for completion
Download Results: Retrieve calculated premiums
Optional: Set up webhooks for notifications

API Endpoint ¶

Base URL: https://api.tigerrating.com/v1/rating/

Synchronous (up to 100 requests):

POST /rating/bulk-calculate/sync/

Asynchronous (100+ requests):

POST /rating/bulk-calculate/async/

Synchronous Bulk Rating ¶

For smaller batches (≤100 requests), get immediate results:

Request:

curl -X POST https://api.tigerrating.com/v1/rating/bulk-calculate/sync/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requests": [
      {
        "product_code": "BOP",
        "effective_date": "2025-01-17",
        "external_reference": "POL-001",
        "risk_characteristics": {
          "territory": "01",
          "class_code": "43211",
          "building_value": 500000
        },
        "coverages": [
          {
            "coverage_code": "BLDG",
            "limit": 500000,
            "deductible": 1000
          }
        ]
      },
      {
        "product_code": "BOP",
        "external_reference": "POL-002",
        ...
      }
    ]
  }'

Response:

{
  "success": true,
  "total": 2,
  "success_count": 2,
  "error_count": 0,
  "results": [
    {
      "external_reference": "POL-001",
      "status": "success",
      "total_premium": 2340.00,
      "coverages": [
        {
          "coverage_code": "BLDG",
          "premium": 1200.00
        },
        {
          "coverage_code": "GL",
          "premium": 1140.00
        }
      ]
    },
    {
      "external_reference": "POL-002",
      "status": "success",
      "total_premium": 2847.00,
      ...
    }
  ]
}

Asynchronous Bulk Rating ¶

For larger batches (>100 requests), use async processing:

Step 1: Submit Job

curl -X POST https://api.tigerrating.com/v1/rating/bulk-calculate/async/ \
  -H "Authorization: Token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "job_name": "Q1 Renewals",
    "webhook_url": "https://yourapp.com/webhooks/bulk-complete",
    "requests": [
      {...},
      {...},
      ...  // up to 10,000 requests
    ]
  }'

Response:

{
  "success": true,
  "job_id": "JOB-2025-01-17-001",
  "status": "queued",
  "total_requests": 1247,
  "estimated_completion": "2025-01-17T15:30:00Z",
  "status_url": "/rating/bulk-jobs/JOB-2025-01-17-001/",
  "results_url": "/rating/bulk-jobs/JOB-2025-01-17-001/results/"
}

Step 2: Poll Status

curl -X GET https://api.tigerrating.com/v1/rating/bulk-jobs/JOB-2025-01-17-001/ \
  -H "Authorization: Token YOUR_TOKEN"

Response (Processing):

{
  "job_id": "JOB-2025-01-17-001",
  "status": "processing",
  "total_requests": 1247,
  "completed_count": 856,
  "success_count": 823,
  "error_count": 33,
  "progress_percentage": 68.6,
  "created_at": "2025-01-17T15:20:00Z",
  "started_at": "2025-01-17T15:20:15Z",
  "estimated_completion": "2025-01-17T15:22:00Z"
}

Response (Completed):

{
  "job_id": "JOB-2025-01-17-001",
  "status": "completed",
  "total_requests": 1247,
  "completed_count": 1247,
  "success_count": 1214,
  "error_count": 33,
  "progress_percentage": 100.0,
  "success_rate": 97.4,
  "created_at": "2025-01-17T15:20:00Z",
  "started_at": "2025-01-17T15:20:15Z",
  "completed_at": "2025-01-17T15:22:03Z",
  "execution_time_ms": 108000,
  "results_url": "/rating/bulk-jobs/JOB-2025-01-17-001/results/"
}

Step 3: Download Results

curl -X GET https://api.tigerrating.com/v1/rating/bulk-jobs/JOB-2025-01-17-001/results/ \
  -H "Authorization: Token YOUR_TOKEN"

Response:

{
  "job_id": "JOB-2025-01-17-001",
  "total_results": 1247,
  "success_count": 1214,
  "error_count": 33,
  "results": [
    {
      "external_reference": "POL-001",
      "status": "success",
      "rating_run_id": "RUN-123456",
      "total_premium": 2340.00,
      "coverages": [...]
    },
    {
      "external_reference": "POL-002",
      "status": "error",
      "errors": ["Invalid territory code: 99"]
    },
    ...
  ]
}

Webhook Notifications ¶

Webhook Notification Flow — *Screenshot Placeholder: Flow showing job completion → webhook POST to your URL → your system processes notification*¶

Set up webhooks for automatic notifications:

Webhook Payload (Job Complete):

{
  "event": "bulk_job.completed",
  "job_id": "JOB-2025-01-17-001",
  "status": "completed",
  "total_requests": 1247,
  "success_count": 1214,
  "error_count": 33,
  "success_rate": 97.4,
  "execution_time_ms": 108000,
  "completed_at": "2025-01-17T15:22:03Z",
  "results_url": "/rating/bulk-jobs/JOB-2025-01-17-001/results/",
  "signature": "sha256=abcdef123456..."
}

Your Webhook Handler:

from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
import json

@csrf_exempt
def bulk_job_webhook(request):
    payload = json.loads(request.body)

    if payload['event'] == 'bulk_job.completed':
        job_id = payload['job_id']
        success_rate = payload['success_rate']

        # Process the notification
        download_and_process_results(job_id)

        # Send notification
        send_email(f"Bulk job {job_id} completed: {success_rate}% success")

    return JsonResponse({'status': 'received'})

Advanced Features ¶

Job Management ¶

Manage your bulk jobs:

View All Jobs: See history of all bulk rating jobs
Filter: By status (queued, processing, completed, failed)
Search: Find specific jobs by name or ID
Cancel: Stop processing jobs (only while queued or processing)
Delete: Remove old jobs and results
Re-run: Submit same data again

Job retention:

Job Retention Policy¶
Item	Retention
Job Metadata	90 days
Results	90 days
Error Logs	90 days

Tip

Download and save results you need long-term. Jobs are automatically deleted after 90 days.

Error Handling ¶

Error Details — *Screenshot Placeholder: Error log showing individual failed ratings with error messages and line numbers*¶

Understanding errors:

Common Errors:

Common Bulk Rating Errors¶
Error	Solution
“Invalid product code”	Check product code matches available products
“Required field missing”	Fill in all required columns
“Territory not found”	Verify territory code is valid
“Value out of range”	Check min/max validation rules
“Invalid date format”	Use YYYY-MM-DD format
“Coverage code invalid”	Verify coverage is available for product

Error Log Format:

Line 45: POL-044
Error: Invalid territory code: '99'
Details: Territory '99' not found in table TERRITORY_CODES
Resolution: Use valid territory code (01-50)

Line 67: POL-066
Error: Building value out of range
Details: Value 50000 below minimum 100000
Resolution: Increase building_value to at least 100000

Handling partial failures:

Download error log: See which ratings failed
Fix errors: Correct data in original CSV
Re-upload: Submit only the corrected rows
Merge results: Combine successful and corrected results

Performance Optimization ¶

Performance Metrics — *Screenshot Placeholder: Performance dashboard showing throughput (ratings/second), cache hit rate, average time per rating*¶

The system is optimized for high-volume processing:

Caching: Product configurations cached (70-90% faster)
Chunking: Processes in batches to manage memory
Parallel Processing: Multiple ratings calculated simultaneously
Database Optimization: Minimized queries through batching

Expected performance:

Processing Speed¶
Batch Size	Processing Time	Throughput
100 ratings	1-2 seconds	50-100 ratings/sec
500 ratings	5-10 seconds	50-100 ratings/sec
1,000 ratings	10-20 seconds	50-100 ratings/sec
5,000 ratings	50-100 seconds	50-100 ratings/sec
10,000 ratings	100-200 seconds	50-100 ratings/sec

Note

Actual performance depends on product complexity, server load, and data characteristics.

Best Practices ¶

Data Preparation ¶

Validate Before Upload: * Check required fields are filled * Verify data formats match template * Remove test/invalid rows
Use External References: * Include your policy/quote numbers * Makes results easier to match back to your system * Helps with error tracking
Batch Logically: * Group by product type * Separate new business from renewals * Keep related risks together
Test First: * Upload small test batch (10-20 rows) * Verify results are correct * Then upload full batch

Error Prevention ¶

Common mistakes to avoid:

❌ Don't: Use different date formats (1/17/2025, Jan 17 2025)
✓ Do: Use consistent YYYY-MM-DD format (2025-01-17)

❌ Don't: Include $ signs or commas in numbers ($500,000)
✓ Do: Use plain numbers (500000)

❌ Don't: Use Excel formulas in CSV
✓ Do: Copy/paste values only

❌ Don't: Mix products in one job
✓ Do: Separate jobs by product type

❌ Don't: Upload without testing
✓ Do: Test with small batch first

Integration Patterns ¶

Pattern 1: Nightly Renewal Processing

# Scheduled job (runs at midnight)
def process_renewals():
    # Get renewals expiring in 30 days
    renewals = get_expiring_policies(days=30)

    # Build bulk request
    requests = [build_rating_request(policy) for policy in renewals]

    # Submit bulk job
    job = submit_bulk_rating(requests, webhook_url=WEBHOOK_URL)

    # Webhook handler will process results when complete

Pattern 2: On-Demand Quote Generator

# API endpoint for quote requests
def generate_quotes(quote_requests):
    if len(quote_requests) <= 100:
        # Synchronous for small batches
        results = bulk_rate_sync(quote_requests)
        return results
    else:
        # Asynchronous for large batches
        job = bulk_rate_async(quote_requests)
        return {"job_id": job.id, "status_url": job.status_url}

Pattern 3: Data Migration

# Migrate historical ratings
def migrate_historical_data():
    # Load from legacy system
    legacy_policies = load_legacy_policies()

    # Convert to bulk rating format
    requests = convert_to_rating_format(legacy_policies)

    # Process in chunks
    chunk_size = 1000
    for chunk in chunks(requests, chunk_size):
        job = submit_bulk_rating(chunk)
        wait_for_completion(job)
        save_results(job)

Troubleshooting ¶

Upload Issues ¶

Issue: “File too large”

Limit: 50 MB per file
Solution: Split into multiple files
Alternative: Use API for very large batches

Issue: “Invalid CSV format”

Common Cause: Extra columns, wrong encoding
Solution: Use the template, save as UTF-8 CSV
Check: Open in text editor to verify format

Processing Issues ¶

Issue: Job stuck in “queued” status

Cause: High server load, queue backup
Solution: Wait; jobs process in order
Check: Contact support if queued >15 minutes

Issue: High error rate (>10%)

Cause: Data quality issues
Solution: Download error log, fix common errors
Prevention: Test with small batch first

Result Issues ¶

Issue: Results don’t match expected premiums

Cause: Effective date, territory, or factor mismatches
Solution: Compare input to individual rating, verify configuration
Check: Run a few ratings individually to debug

Issue: Missing results

Cause: Job still processing or failed
Solution: Check job status, review error log
Retry: Can re-submit failed ratings

API Issues ¶

Issue: Authentication failures

{"detail": "Authentication credentials were not provided."}

Solution: Include Authorization header with valid token
Check: Token hasn’t expired

Issue: Rate limit exceeded

{"detail": "Request was throttled."}

Solution: Reduce submission frequency
Alternative: Use async endpoint for large batches
Contact: Support to increase limits

Next Steps ¶

Try It: Upload your first CSV file
Learn More: See API Integration for API details
Optimize: Read Performance Optimization for best performance
Automate: Integrate with your systems

Tip

Start small! Upload 10-20 test ratings first to validate your data format and understand the process. Then scale up to full batches.

Warning

Always download and save results you need. Bulk jobs and results are automatically deleted after 90 days.

Bulk Rating¶

Overview ¶

What is Bulk Rating?¶

Key Features ¶

When to Use Bulk Rating ¶

Getting Started ¶

Accessing Bulk Rating ¶

Permissions Required ¶

Using CSV Upload ¶

Step 1: Prepare Your CSV File ¶

CSV Format ¶

Step 2: Fill In Your Data ¶

Step 3: Upload Your File ¶

Step 4: Monitor Progress ¶

Step 5: Download Results ¶

Using the API ¶

API Overview ¶

API Endpoint ¶

Synchronous Bulk Rating ¶

Asynchronous Bulk Rating ¶

Webhook Notifications ¶

Advanced Features ¶

Job Management ¶

Error Handling ¶

Performance Optimization ¶

Best Practices ¶

Data Preparation ¶

Error Prevention ¶

Integration Patterns ¶

Troubleshooting ¶

Upload Issues ¶

Processing Issues ¶

Result Issues ¶

API Issues ¶

Next Steps ¶

tiger Rating

Navigation

Related Topics