Documentation

ES Rating Documentation

Build, deploy, and operate insurance rating programs. Public concepts and integration docs are below; account-specific things like API keys, webhook secrets, and live deployment status live inside the studio.

What ES Rating is

ES Rating is an AI-powered platform for designing, deploying, and operating insurance rating programs. Managing General Agents (MGAs), wholesalers, program administrators, and carriers describe a program in plain English, and the platform generates the form schema, rating logic, customer portals, document templates, and integrations needed to take the program live.

A single program covers the full lifecycle: quote → bind → issue → endorse → renew → cancel. The same program can be deployed three ways — a hosted portal on esrating.com, an embeddable iframe widget for partner sites, or a third-party-distributable instance in the Distribution Hub.

Core concepts

Program

An insurance offering — line of business, states, rating tables, forms, workflow. Built once in AI Studio, deployed many ways.

Schema

The form fields users fill out — pages, fields, conditional branches, required validation. Drives the application.

Rating spec

Variables, lookup tables, formulas, factors, surcharges, underwriting rules. Calculates premium from form data.

Portal

The customer-facing app. Public-anon (consumers), agent-login, or embedded iframe — all driven by the same program.

Deployment

A program version published to a subdomain. Test and Live are separate slots so you can verify before flipping billing on.

Distributor

A third-party partner authorized to embed your program. Tracked separately, with their own keys + commission split.

Public docs vs. in-app docs

Everything on this page is open and crawlable — no login required. Anything tied to your account or tenant lives inside the studio.

📖 Public (here)

Concepts, getting-started, integration overviews
JS SDK install + code samples
REST API endpoint reference
Webhook event catalog + signature verification
Security & pricing concepts

🔐 Inside the studio (sign in)

Your API keys + webhook secrets
Stripe/SignWell credential setup
Your live deployments + delivery logs
Tenant config and customer-specific docs
Sandbox / live environment toggles

Open Studio →

Quick Start

1
Sign up at app.esrating.com. Free account, no credit card required.
2
Verify your email by clicking the link sent to your inbox.
3
Open AI Studio from the sidebar and describe your insurance program. Include the line of business, states, rating basis, class codes, and rates.
4
Review and adjust what the AI generates. Use the tabs (Pages, Rating, Templates, Billing, Integrations) to fine-tune.
5
Publish and deploy from the Deployment tab. Choose a subdomain and your portal is live.

Platform Guides

Building a Program with AI

The AI Studio is where you create and manage your insurance programs. You can describe your program in plain English, attach a PDF specification sheet, or paste rating tables directly into the chat.

Starting a new program: Click "+ New" in the Projects sidebar, then describe your program. Include the line of business, target states, rating basis (per $1,000 of payroll, gross sales, etc.), class codes with rates, and any limit or deductible options.

Attaching documents: Drag and drop a PDF spec sheet or ACORD form directly into the chat. The AI reads the document and builds the program from it. Images (PNG, JPG) are also supported.

Iterating: After the initial build, continue the conversation to make changes. "Add a territory factor for Oregon," "Change the minimum premium to $1,500," or "Add a class code for roofers at $45 per thousand."

Multiple programs: Each program is a separate project in the sidebar. You can have multiple programs active at the same time.

Rating Engine

The rating engine calculates premiums using the formulas, rate tables, and rules defined in your program. All calculations are deterministic and reproducible.

Rating tab: View and edit the rating formulas, rate tables, and underwriting rules. The AI generates these from your description, but you can manually adjust any values.

Formulas: Written as simple expressions like premium = (payroll / 1000) * baseRate * stateFactor * limitFactor. The engine evaluates them in order.

Rate tables: Define base rates by class code, territory factors by state, limit multipliers, deductible credits, and any other factor tables your program needs.

Minimum premium: Set a floor premium that applies when the calculated premium is below the threshold.

Referral rules: Define conditions that trigger manual underwriter review instead of auto-quoting (e.g., "total payroll over $2,000,000").

Eligibility rules: Define knockout conditions that auto-decline a submission (e.g., "less than 3 years in business").

Configuring Workflow

The workflow defines what steps a user goes through when using your portal: application, quote, forms, signing, payment, and issuance.

Flow templates: Choose from Quick Quote (app, quote, pay, policy), Standard (app, forms, rating review, quote, sign, pay, policy), Submission (app, forms, UW review, quote, bind), or Custom.

Toggling steps: Enable or disable individual workflow steps. Disable payment for quote-only programs, disable signing if e-signatures are not needed, or disable issuance for submission-only workflows.

Reordering: Drag steps to change the order. For example, move payment before signing or forms before the quote summary.

Permissions: Control who can create quotes, bind, issue, endorse, and cancel. Set permissions per user role (agent, admin, insured).

Payments (Stripe Connect)

ES Rating uses Stripe Connect for payment processing. Payments flow through your Stripe account with destination charges.

Setup: Connect your Stripe account through the Settings page. ES Rating uses Stripe Connect Express, which gives you a Stripe dashboard for managing payouts, refunds, and disputes.

Payment timing: Configure when payment is collected in the workflow settings: at bind, at issuance, or at a custom step.

Accepted methods: Card payments and ACH bank transfers are supported through Stripe.

Test mode: While your portal is in test mode, payments use Stripe's test keys. No real charges are processed. Use Stripe's test card numbers (e.g., 4242 4242 4242 4242) to simulate payments.

E-Signatures (SignWell)

ES Rating integrates with SignWell for embedded electronic signatures directly within the portal workflow.

Setup: Add your SignWell API key and webhook secret in the Vault Secrets page. The AI Studio will configure the signing step in your workflow.

Signing flow: When a user reaches the signing step, they see the documents embedded in the portal. They can review and sign without leaving the page.

Timing: Configure signing to occur before bind, before issuance, or at a custom point in the workflow.

Deploying a Portal

Once your program is configured, deploy it as a live portal that your agents, brokers, or insureds can access.

Publishing: Click "Save New Version" in the Deployment tab to create a versioned snapshot of your program. This captures the current schema, rating, forms, and workflow.

Deploying: Click "Deploy to Subdomain" and choose a subdomain (e.g., my-program.esrating.com). Your portal is live immediately.

Test mode: All new portals start in test mode. No real payments are processed, no real signatures are sent, and all documents are watermarked "TRIAL."

Going live: When ready for production, click "Switch to Live Mode." This requires MFA verification. Live mode uses real Stripe payments, real SignWell signatures, and issues real policies.

Custom domains: You can point your own domain (e.g., quotes.yourcompany.com) to your portal via a CNAME record.

Updates: After making changes to your program, publish a new version and redeploy. Existing quotes follow the workflow from when they were created; new quotes use the latest version.

Document Templates

ES Rating generates professional PDF documents for quotes, binders, policies, certificates, endorsements, and cancellations.

AI-generated templates: The AI creates document templates based on your program. View and customize them in the Templates tab.

Uploading carrier forms: Upload ISO or carrier PDF forms (e.g., CG 00 01). Use the Document Builder to visually place data fields on the PDF pages. At issuance, the system stamps your policy data onto the original form.

Template types: Quote letters, binders, dec pages, policy forms, certificates of insurance, endorsements, cancellation notices, renewal notices, and reinstatement letters.

Fees, Taxes, and Commissions

Configure policy fees, state-specific tax rates, and commission schedules that are automatically calculated at quote time.

Fee schedules: Define policy fees, broker fees, inspection fees, and custom fees. Fees can be flat amounts or percentage-based with min/max limits.

Tax rates: Configure surplus lines taxes, stamping fees, fire marshal fees, and municipal taxes by state. Bulk import all 50 states at once.

Commission schedules: Define MGA commission rates, broker overrides, agency commissions, and agent splits. Commission entries are automatically created at bind and issuance.

User Management

Manage both studio users (your internal team) and portal users (agents, brokers, insureds) from the Users page.

Studio users: Invite team members with roles (admin, manager, member, viewer). Each role has specific permissions for what they can view and manage.

Portal users: Created automatically when a portal is deployed. Users can be invited individually or in bulk (paste a list of emails). Assign roles and permissions per user.

Agencies and groups: Organize portal users into agencies. Users within an agency can see each other's quotes and policies.

API keys: Portal users with API access can generate API keys for programmatic access to quotes and documents.

API Reference

Every deployed portal includes a full REST API for programmatic access. API documentation is available within each portal's API tab, including:

Quotes: Create, retrieve, update, and list quotes
Policies: Retrieve and list policies
Rating: Calculate premiums via API
Documents: Generate and download PDFs
Endorsements: Create and manage endorsements
Renewals: Process renewal quotes

Authentication is via portal API keys (esr_… format, generated in the portal dashboard). Keys can optionally be pinned to a fixed egress IP via the allow-list field. All endpoints support JSON request and response bodies.

An interactive "Try It" tab is available in each deployed portal for testing API calls directly in the browser.

Distribution Hub keys

For third-party partner backends, every Distributor in your Distribution Hub gets two key types:

pk_test_… / pk_live_… — publishable, browser-safe. Used to derive a session URL.
sk_test_… / sk_live_… — secret, backend-only. Optionally IP-restricted. Used to mint embed sessions:

POST /v1/embed/sessions
Authorization: Bearer sk_live_…
{ "user_id": "their-id", "email": "agent@partner.com", "metadata": { ... } }
→ { "session_url": "https://api.esrating.com/v1/embed/start?session=…" }

Issue, rotate, and revoke keys from Distribution → (your distributor) → API keys.

Embed SDKs

Drop-in JavaScript and React packages for embedding the quote flow on any website. Same iframe contract as the raw /v1/embed/start URL — the SDKs just give you a typed API + auto-resize + clean event callbacks.

HTML / Vanilla JS @esrating/embed-js

Add a single <script> tag and call ESRating.mount(). ~30 KB gzipped, no dependencies.

<div id="esr"></div>
<script src="https://embed.esrating.com/v1/embed.umd.js"></script>
<script>
  ESRating.mount('#esr', {
    publishableKey: 'pk_live_...',
    fetchSessionUrl: async () => {
      // Your backend mints the session via POST /v1/embed/sessions
      const res = await fetch('/api/start-session', { method: 'POST' });
      return (await res.json()).session_url;
    },
    onBound: (policy) => location.href = '/policy/' + policy.number,
    onError: (err) => alert(err.message),
  });
</script>

Or via npm: npm i @esrating/embed-js

React @esrating/embed-react

Typed component with React lifecycle handling. Re-mounts on auth-source prop changes; callbacks update without remounting via internal refs.

import { ESRatingWidget } from '@esrating/embed-react';

export default function InsurancePage() {
  return (
    <ESRatingWidget
      publishableKey={process.env.NEXT_PUBLIC_ESRATING_PK}
      fetchSessionUrl={async () => {
        const res = await fetch('/api/start-session', { method: 'POST' });
        return (await res.json()).session_url;
      }}
      onBound={(policy) => router.push('/policy/' + policy.number)}
      onError={(err) => toast.error(err.message)}
      style={{ minHeight: 600 }}
    />
  );
}

Install: npm i @esrating/embed-react (peer dep: React 17+)

Server-side session mint POST /v1/embed/sessions

Both SDKs above ask your backend for a session URL. Your backend mints it with your sk_live_ secret key — the browser never sees the secret.

// Node / Express example
app.post('/api/start-session', async (req, res) => {
  const r = await fetch('https://api.esrating.com/v1/embed/sessions', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.ESRATING_SK_LIVE,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      user_id: req.user.id,
      email: req.user.email,
      metadata: { partnerOrderId: req.user.orderId },
    }),
  });
  res.json(await r.json());  // { session_url, expires_at, embed_session_id }
});

Server SDKs & OpenAPI

Typed clients for the partner-facing API. Both ship a webhook signature verifier with the same ergonomics as Stripe's SDKs — pass raw body + header + secret, get back a typed event or a thrown error.

Node.js @esrating/node

npm install @esrating/node

import { ESRating } from '@esrating/node';

const esrating = new ESRating({ apiKey: process.env.ESRATING_SK_LIVE });

const session = await esrating.embed.createSession({
  user_id: 'partner-user-123',
  email: 'agent@partner.com',
  metadata: { partnerOrderId: 'abc' },
});

// Webhooks (Express raw-body example):
app.post('/webhooks/esrating',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = esrating.webhooks.constructEvent(
      req.body,
      req.headers['x-esrating-signature'],
      process.env.ESRATING_WEBHOOK_SECRET,
    );
    if (event.event === 'quote.bound') { /* ... */ }
    res.json({ received: true });
  });

Python esrating

pip install esrating

from esrating import ESRating

esrating = ESRating(api_key=os.environ["ESRATING_SK_LIVE"])

session = esrating.embed.create_session(
    user_id="partner-user-123",
    email="agent@partner.com",
    metadata={"partnerOrderId": "abc"},
)

# Webhooks (Flask raw-body example):
@app.post("/webhooks/esrating")
def esrating_webhook():
    event = esrating.webhooks.construct_event(
        raw_body=request.get_data(as_text=True),
        signature=request.headers.get("X-ESRating-Signature"),
        secret=os.environ["ESRATING_WEBHOOK_SECRET"],
    )
    if event["event"] == "quote.bound":
        ...
    return {"received": True}

OpenAPI 3.1

Full machine-readable API spec — load it in Swagger UI, Postman, or your favorite codegen tool.

curl https://api.esrating.com/v1/openapi.json | jq .

Updated on every backend deploy. CORS-enabled. X-Spec-Version response header for cache-busting.

Frequently Asked Questions

How long does it take to build a program?

Most programs can be built and deployed in under an hour. Simple programs (one state, a few class codes) take minutes. Complex programs with multiple states, hundreds of class codes, and territory factors take longer but are still measured in hours, not weeks.

Can I modify the program after deploying?

Yes. Make changes in AI Studio, publish a new version, and redeploy. Existing quotes and policies are not affected; they continue using the version that was active when they were created.

Is my data secure?

Yes. All data is encrypted at rest (AES-256) and in transit (TLS 1.2+). We run on Google Cloud Platform with IAM-locked services, MFA on sensitive operations, and comprehensive audit logging. See our Security page for details.

Do I need to write code?

No. The entire platform is designed to be used without writing code. Describe your program in plain English, configure options through the UI, and deploy with a click. For advanced users, the REST API, webhooks, JavaScript embed SDK, and integration builder provide programmatic control.

What happens when I go live?

Going live can enable real payments, e-signatures, and production policy workflows depending on your program configuration. A program subscription ($500/month per active live program) applies, and usage fees may apply for quotes, binds, e-signatures, AI form population, and address validation. You can switch back to test mode by contacting support.

How do I get support?

Email support@esrating.com or use the contact form. We respond within one business day.

Vertical quickstarts

End-to-end recipes for the most common embedded-insurance use cases. Each guide walks through schema, rating, forms, and the partner integration for that vertical. Coming soon — drop us a line if you'd like priority access to one of these.

🏗️

Contractors GL

General Liability for trades — payroll-based rating, COI generation, additional-insured endorsements.

Coming soon

💻

Cyber for SaaS

Tech E&O + Cyber for software companies — revenue-based rating, ransomware sub-limits.

Coming soon

🌱

Pollution & Environmental

CPL / PLL for site cleanup, contractors pollution, premises pollution liability.

Coming soon

Rating engine overview

The rating engine calculates premium from form data using variables, lookup tables, and formulas. Tables hold rate factors keyed by class code, state, limit, deductible, etc. Formulas reference variables and tables — for example base_premium = (annual_payroll / 1000) * class_rate. Underwriting rules (e.g. refer if class_code == 'Roofing' && mailing_state == 'WA') flag risks for human review without blocking the quote. State-specific rates, minimum premiums, surcharges, and conditional credits are all expressible. The AI builder writes most of this for you from the description; you tweak in the Rating tab.

Document generation overview

Programs produce documents at lifecycle points (quote letter, binder, policy, certificate, endorsement, cancellation). Two paths: AI-generated templates render to PDF via Puppeteer with your branding; uploaded carrier/ISO forms (CG 00 01, ACORD, etc.) are preserved exactly and stamped with field overlays. On upload, GPT-5.5 detects fillable fields and pre-stamps overlays so the Document Builder opens to a mostly-completed form. Forms can attach unconditionally, conditionally (e.g. only when class_code is Roofing), or by state.

Portal types

Public-anon — no login, anyone can quote. Use for consumer widgets and partner-side embeds. Public-anon deployments also expose a separate /admin URL for staff to view bound policies and create quotes manually.
Agent login required — staff portal. Producers, underwriters, CSRs each get a role with scoped permissions.
Admin-managed users — same as agent but invitation-only. The MGA controls who can sign in.
Embedded iframe — drop into any partner site via JavaScript SDK or plain iframe. JWT-gated for trusted partners; public-anon for no-auth widgets.

Distribution Hub overview

The Distribution Hub lets you ship a single program to many third-party partners — agencies, marketplaces, lender networks. Each partner gets isolated branding, their own publishable+secret key pair, an admin invite to a Partner Portal at partners.esrating.com, and an automatic three-way Stripe Connect commission split (carrier/MGA → partner → ES Rating platform fee). Track quotes, binds, and revenue per distributor. Anti-rebating heuristics and per-state disclosure injection handle compliance.

Webhooks overview

Partner backends receive HMAC-signed POSTs at quote/bind/issue/payment/signature events. Signature header format mirrors Stripe (t=<timestamp>,v1=<hex_hmac>) with a 5-minute replay-tolerance window. Use the official @esrating/node or esrating Python SDK for verification.

🔐 Your webhook secret + delivery log live inside the studio. Sign in to manage them.

Deployment overview

Programs deploy in two slots: Test (zero billing, no real Stripe charges) and Live (real customers, billing applies). Live is locked until Test is deployed first. Both require quote and policy number sequences configured. Deploys produce a stable URL like esrating.com/portal/<subdomain>; you can also point a custom domain at it.

Security overview

All data is encrypted at rest (AES-256) and in transit (TLS 1.2+). The platform runs on Google Cloud Platform with IAM-locked services, MFA enforced on privileged actions (deploy, publish, going live), and a comprehensive audit log compatible with SOC2 evidence collection. Webhook payloads are HMAC-signed; embed JWTs use HS256 with per-deployment secrets and 1-hour TTL. Public anonymous portal sessions auto-expire and use one-off PortalUser records that don't accumulate in your admin staff list. Full security disclosures: esrating.com/security.

Pricing & billing concepts

Test mode is free forever — build, test, and iterate at no cost. Live programs are $500/month per active live program. Usage fees may apply when a program is live (per-quote, per-bind, e-signature, AI form population, address validation). For the latest tiers and rates see esrating.com/pricing.

Billing is prepaid via a balance pool with auto-refill. The studio's Billing tab shows your balance, recent transactions, and payment methods.

Need help?

Our team is here to help you get your program live.

Start free in test mode Email Support Book a Demo

ES Rating Documentation

What ES Rating is

Core concepts

Public docs vs. in-app docs

Quick Start

Platform Guides

Building a Program with AI

Rating Engine

Configuring Workflow

Payments (Stripe Connect)

E-Signatures (SignWell)

Deploying a Portal

Document Templates

Fees, Taxes, and Commissions

User Management

API Reference

Embed SDKs

Server SDKs & OpenAPI

Frequently Asked Questions

Vertical quickstarts

Contractors GL

Cyber for SaaS

Pollution & Environmental

Rating engine overview

Document generation overview

Portal types

Distribution Hub overview

Webhooks overview

Deployment overview

Security overview

Pricing & billing concepts

Need help?

ES Rating Assistant