API Integration

This guide explains how to integrate external systems with the tiger Rating Engine REST API for automated premium calculations, product queries, and rating history retrieval.

API Overview

Architecture

Screenshot Placeholder: Architecture diagram showing Client Applications → API Gateway → Authentication → REST API → Rating Engine → Database

The tiger Rating Engine API provides:

• RESTful Design: Standard HTTP methods (GET, POST, PUT, DELETE)

• JSON Format: All requests and responses in JSON

• Token Authentication: Secure Bearer token authentication

• Rate Limiting: Prevent overload with built-in limits

• Versioning: API version in URL for stability

• Comprehensive Documentation: Interactive Swagger/OpenAPI docs

Base URL

Production:  https://api.tigerrating.com/v1/
Staging:     https://staging-api.tigerrating.com/v1/
Development: https://dev-api.tigerrating.com/v1/

Endpoints Overview

Authentication

Obtaining API Credentials

Screenshot Placeholder: Developer portal showing API Keys section with client ID, client secret (hidden), and “Generate New Key” button

To get API access:

1. Log into Developer Portal at https://developers.tigerrating.com

2. Navigate to API Keys

3. Click Create New Application

4. Enter application details:

   Application Name: My Rating System
   Description: Integration for automated quotes
   Environment: Production
   Allowed IPs: 192.168.1.100, 10.0.0.0/24 (optional)
   

5. Save and copy credentials:

   {
     "client_id": "app_3a5b7c9d2e4f6g8h",
     "client_secret": "secret_1a2b3c4d5e6f7g8h9i0j",
     "api_endpoint": "https://api.tigerrating.com/v1/"
   }
   

Token Authentication

Screenshot Placeholder: Sequence diagram showing Client → Auth Endpoint → Token Response → API Calls with Token

Get authentication token:

Request:

curl -X POST https://api.tigerrating.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "app_3a5b7c9d2e4f6g8h",
    "client_secret": "secret_1a2b3c4d5e6f7g8h9i0j"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_9h8g7f6e5d4c3b2a1"
}

Using the Token

Include token in all API requests:

curl -X GET https://api.tigerrating.com/v1/rating/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Refresh

Before expiration, refresh your token:

curl -X POST https://api.tigerrating.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "refresh_9h8g7f6e5d4c3b2a1"
  }'

Core API Operations

Listing Available Products

Screenshot Placeholder: JSON response showing array of products with codes, names, and effective dates

Endpoint: GET /rating/products

Request:

curl -X GET https://api.tigerrating.com/v1/rating/products \
  -H "Authorization: Bearer {token}"

Response:

{
  "success": true,
  "data": [
    {
      "product_code": "BOP",
      "product_name": "Business Owners Policy",
      "description": "Comprehensive coverage for small businesses",
      "effective_date": "2025-01-01",
      "is_active": true
    },
    {
      "product_code": "GL_POLICY",
      "product_name": "General Liability",
      "description": "General liability coverage",
      "effective_date": "2025-01-01",
      "is_active": true
    }
  ],
  "count": 2
}

Getting Product Details

Endpoint: GET /rating/products/{product_code}

Request:

curl -X GET https://api.tigerrating.com/v1/rating/products/BOP \
  -H "Authorization: Bearer {token}"

Response:

{
  "success": true,
  "data": {
    "product_code": "BOP",
    "product_name": "Business Owners Policy",
    "description": "Comprehensive coverage for small businesses",
    "effective_date": "2025-01-01",
    "rating_factors": [
      {
        "factor_code": "territory",
        "factor_name": "Territory",
        "data_type": "text",
        "required": true,
        "validation": {
          "allowed_values": ["001", "002", "003"]
        }
      },
      {
        "factor_code": "building_value",
        "factor_name": "Building Value",
        "data_type": "decimal",
        "required": true,
        "validation": {
          "min_value": 50000,
          "max_value": 10000000
        }
      }
    ],
    "available_coverages": [
      "property",
      "general_liability",
      "business_income"
    ]
  }
}

Calculating Premium

Screenshot Placeholder: Flow diagram showing Request → Validation → Calculation → Response with example JSON

Endpoint: POST /rating/calculate

Request:

curl -X POST https://api.tigerrating.com/v1/rating/calculate \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "product_code": "BOP",
    "effective_date": "2025-02-01",
    "external_reference": "QUOTE-2025-001",
    "rating_factors": {
      "territory": "001",
      "building_value": 500000,
      "contents_value": 100000,
      "building_class": "B",
      "occupancy_type": "OFFICE",
      "liability_limit": 1000000,
      "deductible": 1000
    }
  }'

Response:

{
  "success": true,
  "data": {
    "run_id": "RUN-2025-02-01-123456",
    "product_code": "BOP",
    "total_premium": 3450.00,
    "status": "SUCCESS",
    "coverages": [
      {
        "coverage_type": "property",
        "premium": 1850.00,
        "limit": 600000
      },
      {
        "coverage_type": "general_liability",
        "premium": 1200.00,
        "limit": 1000000
      },
      {
        "coverage_type": "business_income",
        "premium": 400.00,
        "limit": 100000
      }
    ],
    "calculation_details": {
      "base_premium": 3000.00,
      "territory_factor": 1.15,
      "class_factor": 1.0,
      "credits_applied": [],
      "taxes_fees": 0.00
    },
    "warnings": [],
    "execution_time_ms": 245
  }
}

Retrieving Rating History

Endpoint: GET /rating/runs

Query Parameters:

Query Parameters

Parameter	Type	Description
start_date	date	Filter runs after this date
end_date	date	Filter runs before this date
product_code	string	Filter by product
external_ref	string	Filter by external reference
status	string	Filter by status (SUCCESS/FAILED)
limit	integer	Number of results (default: 50)
offset	integer	Pagination offset (default: 0)

Request:

curl -X GET "https://api.tigerrating.com/v1/rating/runs?start_date=2025-02-01&limit=10" \
  -H "Authorization: Bearer {token}"

Response:

{
  "success": true,
  "data": [
    {
      "run_id": "RUN-2025-02-01-123456",
      "created_at": "2025-02-01T10:30:00Z",
      "product_code": "BOP",
      "external_reference": "QUOTE-2025-001",
      "total_premium": 3450.00,
      "status": "SUCCESS"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 10,
    "offset": 0,
    "has_next": true
  }
}

Advanced Integration Patterns

Batch Rating

Screenshot Placeholder: Diagram showing batch submission → processing queue → results retrieval

For multiple calculations:

Request:

curl -X POST https://api.tigerrating.com/v1/rating/batch \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "batch_id": "BATCH-2025-02-01-001",
    "calculations": [
      {
        "reference": "QUOTE-001",
        "product_code": "BOP",
        "effective_date": "2025-02-01",
        "rating_factors": {...}
      },
      {
        "reference": "QUOTE-002",
        "product_code": "BOP",
        "effective_date": "2025-02-01",
        "rating_factors": {...}
      }
    ]
  }'

Response:

{
  "success": true,
  "data": {
    "batch_id": "BATCH-2025-02-01-001",
    "status": "PROCESSING",
    "total_items": 2,
    "processed": 0,
    "estimated_completion": "2025-02-01T10:35:00Z",
    "results_url": "/rating/batch/BATCH-2025-02-01-001/results"
  }
}

Webhook Integration

Screenshot Placeholder: Webhook configuration interface with URL, events selection, and secret key

Configure webhooks for async notifications:

Setup Webhook:

curl -X POST https://api.tigerrating.com/v1/webhooks \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/rating",
    "events": ["calculation.completed", "batch.completed"],
    "secret": "webhook_secret_key"
  }'

Webhook Payload:

{
  "event": "calculation.completed",
  "timestamp": "2025-02-01T10:30:15Z",
  "data": {
    "run_id": "RUN-2025-02-01-123456",
    "external_reference": "QUOTE-2025-001",
    "status": "SUCCESS",
    "total_premium": 3450.00
  },
  "signature": "sha256=abcdef123456..."
}

Rate Limiting

Screenshot Placeholder: Response headers showing X-RateLimit headers with remaining calls and reset time

API rate limits:

Rate Limits by Plan

Plan	Per Min	Per Hour	Per Day	Burst
Basic	60	1,000	10,000	100
Standard	300	5,000	50,000	500
Premium	1,000	20,000	200,000	2,000

Check headers for limit status:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1612137600

Error Handling

Error Response Format

All errors follow consistent format:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid rating factors provided",
    "details": [
      {
        "field": "building_value",
        "error": "Value must be between 50000 and 10000000"
      }
    ],
    "request_id": "req_abc123def456"
  }
}

Common Error Codes

Retry Strategy

Implement exponential backoff:

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session():
    session = requests.Session()
    retry = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504]
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount("https://", adapter)
    return session

def calculate_premium(data, token):
    session = create_session()
    headers = {"Authorization": f"Bearer {token}"}

    try:
        response = session.post(
            "https://api.tigerrating.com/v1/rating/calculate",
            json=data,
            headers=headers,
            timeout=30
        )
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error: {e}")
        # Implement retry logic
        time.sleep(2 ** attempt)  # Exponential backoff

Client Libraries

Python SDK

Install the Python client:

pip install tigerrating-python

Usage example:

from tigerrating import TigerRatingClient

# Initialize client
client = TigerRatingClient(
    client_id="app_3a5b7c9d2e4f6g8h",
    client_secret="secret_1a2b3c4d5e6f7g8h9i0j",
    environment="production"
)

# Calculate premium
result = client.calculate_premium(
    product_code="BOP",
    effective_date="2025-02-01",
    factors={
        "territory": "001",
        "building_value": 500000,
        "building_class": "B",
        "occupancy_type": "OFFICE",
        "liability_limit": 1000000,
        "deductible": 1000
    }
)

print(f"Total Premium: ${result.total_premium}")
for coverage in result.coverages:
    print(f"  {coverage.type}: ${coverage.premium}")

JavaScript/Node.js SDK

Install the Node.js client:

npm install @tigerrating/api-client

Usage example:

const TigerRating = require('@tigerrating/api-client');

// Initialize client
const client = new TigerRating({
  clientId: 'app_3a5b7c9d2e4f6g8h',
  clientSecret: 'secret_1a2b3c4d5e6f7g8h9i0j',
  environment: 'production'
});

// Calculate premium
async function calculatePremium() {
  try {
    const result = await client.calculatePremium({
      productCode: 'BOP',
      effectiveDate: '2025-02-01',
      factors: {
        territory: '001',
        building_value: 500000,
        building_class: 'B',
        occupancy_type: 'OFFICE',
        liability_limit: 1000000,
        deductible: 1000
      }
    });

    console.log(`Total Premium: $${result.totalPremium}`);
    result.coverages.forEach(coverage => {
      console.log(`  ${coverage.type}: $${coverage.premium}`);
    });
  } catch (error) {
    console.error('Error:', error.message);
  }
}

calculatePremium();

.NET SDK

Install via NuGet:

dotnet add package TigerRating.Client

Usage example:

using TigerRating.Client;

var client = new TigerRatingClient(
    clientId: "app_3a5b7c9d2e4f6g8h",
    clientSecret: "secret_1a2b3c4d5e6f7g8h9i0j",
    environment: Environment.Production
);

var factors = new Dictionary<string, object>
{
    {"territory", "001"},
    {"building_value", 500000},
    {"building_class", "B"},
    {"occupancy_type", "OFFICE"},
    {"liability_limit", 1000000},
    {"deductible", 1000}
};

var result = await client.CalculatePremiumAsync(
    productCode: "BOP",
    effectiveDate: DateTime.Parse("2025-02-01"),
    factors: factors
);

Console.WriteLine($"Total Premium: ${result.TotalPremium}");

Testing and Development

API Sandbox

Screenshot Placeholder: Interactive API sandbox with request builder, parameter inputs, and response viewer

Test API calls in sandbox:

1. Navigate to https://sandbox.tigerrating.com

2. Use test credentials:

   {
     "client_id": "test_client_id",
     "client_secret": "test_secret_key"
   }
   

3. No charges for sandbox calls

4. Data resets daily

Postman Collection

Screenshot Placeholder: Postman interface showing tiger Rating API collection with folders for Auth, Products, Calculations

Import our Postman collection:

1. Download from https://api.tigerrating.com/postman/collection.json

2. Import into Postman

3. Set environment variables:

   {
     "base_url": "https://api.tigerrating.com/v1",
     "client_id": "your_client_id",
     "client_secret": "your_client_secret"
   }
   

4. Run example requests

Mock Server

Use mock server for development:

docker run -p 8080:8080 tigerrating/mock-api:latest

Mock endpoints return realistic responses without actual calculations.

Monitoring and Analytics

API Dashboard

Screenshot Placeholder: Dashboard showing API call volume graph, success rate, average latency, and top endpoints

Monitor usage at https://developers.tigerrating.com/dashboard:

• Call Volume: Requests per time period

• Success Rate: Percentage of successful calls

• Latency: Average response times

• Error Analysis: Common error patterns

• Usage by Endpoint: Most used operations

Logging Best Practices

Log important events:

import logging
import json

logger = logging.getLogger('tigerrating')

def log_api_call(endpoint, request_data, response):
    logger.info(json.dumps({
        "event": "api_call",
        "endpoint": endpoint,
        "request": {
            "product_code": request_data.get("product_code"),
            "external_ref": request_data.get("external_reference")
        },
        "response": {
            "run_id": response.get("data", {}).get("run_id"),
            "status": response.get("success"),
            "premium": response.get("data", {}).get("total_premium")
        },
        "timestamp": datetime.utcnow().isoformat()
    }))

Security Best Practices

Protecting Credentials

Never expose credentials:

# BAD - Don't hardcode credentials
client_id = "app_3a5b7c9d2e4f6g8h"  # Never do this!

# GOOD - Use environment variables
import os
client_id = os.environ.get('TIGERRATING_CLIENT_ID')
client_secret = os.environ.get('TIGERRATING_CLIENT_SECRET')

# BETTER - Use secret management
from aws_secretsmanager import get_secret
credentials = get_secret('tigerrating/api/credentials')

IP Whitelisting

Restrict access by IP:

Screenshot Placeholder: Security settings showing IP whitelist with ranges and descriptions

1. Go to Security Settings

2. Add allowed IP ranges

3. Enable IP restriction

Webhook Security

Verify webhook signatures:

import hmac
import hashlib

def verify_webhook(payload, signature, secret):
    expected = hmac.new(
        secret.encode(),
        payload.encode(),
        hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(
        f"sha256={expected}",
        signature
    )

Migration Guide

From Manual Process

Transition steps:

1. Phase 1: Test API in sandbox

2. Phase 2: Pilot with select products

3. Phase 3: Parallel run (manual + API)

4. Phase 4: Full API adoption

From Legacy System

Migration checklist:

☐ Map legacy fields to API fields
☐ Convert data formats
☐ Test calculation accuracy
☐ Implement error handling
☐ Set up monitoring
☐ Train staff
☐ Plan rollback strategy

Support Resources

Documentation

• API Reference: https://api.tigerrating.com/docs

• OpenAPI Spec: https://api.tigerrating.com/openapi.json

• Change Log: https://developers.tigerrating.com/changelog

• Status Page: https://status.tigerrating.com

Getting Help

• Developer Forum: https://forum.tigerrating.com/developers

• Support Email: api-support@tigerrating.com

• Slack Channel: tigerrating.slack.com #api-support

• Office Hours: Thursdays 2-3 PM EST

Next Steps

• Quick Start: Getting Started

• Product Setup: Product Configuration

• Manual Rating: Performing Calculations

• User Guide: tiger Rating Engine User Guide

Tip

Start with the sandbox environment to test your integration before using production credentials.

Warning

Rate limits apply to all API calls. Monitor your usage to avoid disruptions.