arrow_back Back to Documentation

OpenAPI Specification

Download the complete OpenAPI 3.0.3 specification for the Surplus Lines Tax API. Use it with Swagger, Postman, or generate client SDKs.

download Download YAML download Download JSON

What's Included

api

Complete API Schema

Full endpoint definitions with request/response schemas, including all parameters for state-specific calculations.

security

Authentication Details

Security scheme definitions for API key authentication via the X-API-Key header.

data_object

Request Examples

Multiple example requests showing basic calculations, wet marine, fire insurance, and more.

error_outline

Error Responses

Comprehensive error code documentation with examples for all error scenarios.

Specification Details

  • check_circle OpenAPI Version: 3.0.3
  • check_circle Base URL: https://api.surpluslinesapi.com/v1
  • check_circle Endpoints: POST /calculate
  • check_circle Authentication: API Key (X-API-Key header)
  • check_circle Coverage: All 50 U.S. states, DC, Puerto Rico, Virgin Islands
  • check_circle Special Parameters: wet_marine, fire_insurance, workers_comp, medical_malpractice, electronic_filing

Usage Examples

Using with Swagger UI

  1. Go to editor.swagger.io
  2. Click File → Import URL
  3. Enter: https://surpluslinesapi.com/docs/openapi/surpluslines-openapi.yaml
  4. The specification will load with interactive documentation
  5. Click Authorize and enter your API key to test endpoints

Tip

You can also download the YAML file and import it directly using File → Import file.

Importing into Postman

  1. Open Postman and click Import
  2. Select the Link tab
  3. Enter: https://surpluslinesapi.com/docs/openapi/surpluslines-openapi.json
  4. Click Continue and then Import
  5. The collection will be created with all endpoints

Alternative

For a pre-configured Postman collection with examples, see our Postman Collection page.

Generating Client SDKs

Use OpenAPI Generator to create client libraries in your preferred language:

Install OpenAPI Generator
npm install @openapitools/openapi-generator-cli -g

Generate SDK

JavaScript openapi-generator-cli generate -i surpluslines-openapi.yaml -g javascript -o ./sdk-js
Python openapi-generator-cli generate -i surpluslines-openapi.yaml -g python -o ./sdk-python
TypeScript openapi-generator-cli generate -i surpluslines-openapi.yaml -g typescript-fetch -o ./sdk-ts
Java openapi-generator-cli generate -i surpluslines-openapi.yaml -g java -o ./sdk-java
C# openapi-generator-cli generate -i surpluslines-openapi.yaml -g csharp -o ./sdk-csharp
PHP openapi-generator-cli generate -i surpluslines-openapi.yaml -g php -o ./sdk-php

More Languages

OpenAPI Generator supports 50+ languages. Run openapi-generator-cli list to see all available generators.

Quick Reference

cURL Example
curl -X POST https://api.surpluslinesapi.com/v1/calculate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key_here" \
  -d '{
    "state": "Texas",
    "premium": 10000
  }'
Response
{
  "success": true,
  "state": "Texas",
  "premium": 10000,
  "taxes": {
    "sl_tax": 485.00,
    "tax_rate": 0.0485,
    "stamping_fee": 18.00,
    "stamping_fee_rate": 0.0018,
    "filing_fee": 0,
    "filing_fee_rate": 0
  },
  "total_tax": 503.00,
  "total_due": 10503.00
}