API Documentation - Surety Rate Calculator

Overview

The Surety Rate Calculator API provides programmatic access to rate management, calculations, and share link functionality. All endpoints return JSON responses.

Base URL: /api/v1

Response Format

All responses follow a consistent format:

{
  "success": true,
  "data": { ... }
}

Error responses include an error object:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message"
  }
}

Authentication

All API endpoints require authentication via API key. Include your key in one of these headers:

X-API-Key Header

curl -H "X-API-Key: rk_live_your_key_here" \
  http://ratecalc.pcl.vrfy.it/api/v1/rates

Authorization Bearer

curl -H "Authorization: Bearer rk_live_your_key_here" \
  http://ratecalc.pcl.vrfy.it/api/v1/rates

Scopes

API keys can have different permission scopes:

Scope	Description
`read`	Read rates, shares, and perform calculations
`write`	Create, update, and delete rates and shares
`admin`	Manage API keys (includes read and write)

Creating an API Key

Generate a new API key using the command line:

npm run create-api-key -- "Key Name" "read,write"

Store your API key securely. It is only shown once at creation.

Rates API

Manage premium and commission rate schedules.

GET /api/v1/rates read

List all rate schedules with optional filtering.

Query Parameters

Parameter	Type	Description
`type`	string	Filter by type: `Premium` or `Commission`
`active`	boolean	Filter by active status (default: true)
`limit`	integer	Max results to return (default: 100)
`offset`	integer	Number of results to skip (default: 0)

Example

curl -H "X-API-Key: YOUR_KEY" \
  "http://ratecalc.pcl.vrfy.it/api/v1/rates?type=Premium&limit=10"

GET /api/v1/rates/:id read

Get a single rate schedule by ID.

Example

curl -H "X-API-Key: YOUR_KEY" \
  "http://ratecalc.pcl.vrfy.it/api/v1/rates/15"

POST /api/v1/rates write

Create a new rate schedule.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique name for the rate
`type`	string	Yes	`Premium` or `Commission`
`bond_type`	string	No	`Contract` or `Commercial`
`tier1_size` - `tier5_size`	number	No	Upper limit for each tier
`tier1_rate` - `tier6_rate`	number	No	Rate as decimal (0.025 = 2.5%)
`is_flat`	boolean	No	Use tier6_rate for all amounts
`max_rate`	number	No	Cap effective rate
`source`	string	No	`Contract` or `SOV`
`term_period`	string	No	`None`, `Month`, or `Year`
`term_skip`	integer	No	Periods before term rate applies
`term_rate`	number	No	Supplemental rate per period

Example

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Custom Premium Rate",
    "type": "Premium",
    "tier1_size": 100000,
    "tier1_rate": 0.025,
    "tier2_size": 500000,
    "tier2_rate": 0.015,
    "tier6_rate": 0.01
  }' \
  "http://ratecalc.pcl.vrfy.it/api/v1/rates"

PUT /api/v1/rates/:id write

Update an existing rate schedule. Partial updates are supported.

DELETE /api/v1/rates/:id write

Deactivate a rate schedule (soft delete).

Calculator API

Perform premium and commission calculations.

POST /api/v1/calculate read

Calculate premium and commission for a bond.

Request Body

Field	Type	Required	Description
`premium_rate_id`	integer	Yes	ID of the premium rate to use
`commission_rate_id`	integer	No	ID of the commission rate (optional)
`contract_amount`	number	Yes	Contract amount in dollars
`maintenance_amount`	number	No	Maintenance bond amount
`maintenance_percent`	number	No	Auto-calculate maintenance as % of contract
`surcharge`	number	No	Surcharge percentage (e.g., 5 for 5%)
`term`	integer	No	Term in years (default: 1)
`duration`	integer	No	Duration in months (default: 12)
`project_name`	string	No	Project name for reference
`client_name`	string	No	Client name for reference
`date`	string	No	Date in YYYY-MM-DD format

Example

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "premium_rate_id": 15,
    "commission_rate_id": 28,
    "contract_amount": 5000000,
    "maintenance_percent": 100,
    "term": 2,
    "duration": 24,
    "project_name": "Highway Project",
    "client_name": "ABC Construction"
  }' \
  "http://ratecalc.pcl.vrfy.it/api/v1/calculate"

Response

{
  "success": true,
  "data": {
    "input": {
      "project_name": "Highway Project",
      "contract_amount": 5000000,
      ...
    },
    "premium": {
      "rate_name": "TX Class B",
      "penalty": 5000000,
      "tiered": true,
      "tiers": [
        { "tier": 1, "amount": 100000, "rate": 0.025, "premium": 2500 },
        ...
      ],
      "base_premium": 47250,
      "supplemental_premium": 5670,
      "total_premium": 62445
    },
    "commission": {
      "rate_name": "SureTec 35%",
      "total_commission": 19318
    },
    "totals": {
      "total_premium": 62445,
      "total_commission": 19318
    }
  }
}

Shares API

Manage shareable calculator links for clients.

GET /api/v1/shares read

List all share links with optional filtering.

Query Parameters

Parameter	Type	Description
`active`	boolean	Filter by active status
`limit`	integer	Max results (default: 100)
`offset`	integer	Results to skip (default: 0)

GET /api/v1/shares/:id read

Get a share link by ID.

GET /api/v1/shares/token/:token read

Get a share link by its public token.

POST /api/v1/shares write

Create a new share link.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Internal name for the share
`premium_rate_id`	integer	Yes	Premium rate to use
`client_name`	string	No	Client name to display
`surcharge`	number	No	Surcharge % (e.g., 5 for 5%)

Example

curl -X POST -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Rate Calculator",
    "premium_rate_id": 15,
    "client_name": "ABC Construction",
    "surcharge": 5
  }' \
  "http://ratecalc.pcl.vrfy.it/api/v1/shares"

Response

{
  "success": true,
  "data": {
    "id": 5,
    "token": "abc123xyz789def0",
    "name": "Client Rate Calculator",
    "share_url": "http://ratecalc.pcl.vrfy.it/s/abc123xyz789def0",
    ...
  }
}

PUT /api/v1/shares/:id write

Update an existing share link.

DELETE /api/v1/shares/:id write

Deactivate a share link (soft delete).

API Keys API

Manage API keys. Requires admin scope.

GET /api/v1/api-keys admin

List all API keys (metadata only, keys are never returned).

POST /api/v1/api-keys admin

Create a new API key. The key is only returned once.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Name for the key
`description`	string	No	Description
`scopes`	string	No	Comma-separated scopes (default: read)
`rate_limit`	integer	No	Requests per hour (null = unlimited)
`expires_at`	string	No	Expiration datetime (ISO 8601)

Response

{
  "success": true,
  "data": {
    "id": 2,
    "key": "rk_live_abc123...",
    "key_prefix": "rk_live_abc1",
    "name": "Production API",
    "scopes": "read,write",
    "warning": "Store this API key securely. It will not be shown again."
  }
}

PUT /api/v1/api-keys/:id admin

Update API key metadata (scopes, rate limit, etc.).

DELETE /api/v1/api-keys/:id admin

Revoke an API key.

Error Handling

The API uses standard HTTP status codes and returns detailed error information.

Status	Code	Description
400	`BAD_REQUEST`	Invalid request parameters
400	`VALIDATION_ERROR`	Input validation failed
401	`UNAUTHORIZED`	Missing API key
401	`INVALID_API_KEY`	Invalid or inactive key
401	`API_KEY_EXPIRED`	Key has expired
403	`INSUFFICIENT_SCOPE`	Key lacks required scope
404	`NOT_FOUND`	Resource not found
409	`CONFLICT`	Resource already exists
500	`INTERNAL_ERROR`	Server error

Example Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "premium_rate_id is required"
  }
}