Getting Started

The Advance API enables insurance agencies to programmatically manage their billing operations — creating invoices (plans), processing payments, managing insureds (customers), tracking producer commissions, and configuring market payouts. The API follows RESTful conventions and uses JSON for request and response bodies.

Base URLs

We recommend using the Sandbox environment for development and testing before moving to Production.

Authentication

All API requests require authentication using a Bearer token. Include your API key in the Authorization header:

Authorization: Bearer your_api_key_here

API keys follow the format advance_live_<32-character-string> (production) or advance_test_<32-character-string> (sandbox) and are issued through the Advance dashboard.

Example request

curl -X GET "https://api.sandbox.advancehq.com/v1/plans" \
  -H "Authorization: Bearer advance_test_k8j2h4g6f9d3s7a1q5w8e0r2t6y9u3i7o1p4" \
  -H "Content-Type: application/json"

Rate Limits

The API enforces rate limits to ensure fair usage. When rate limited, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your integration to handle rate limiting gracefully.

Errors

All errors return a consistent JSON body with a machine-readable error_code and a human-readable message. See the Errors page for the full list of error codes, status codes, and retry guidance.

Setup Checklist

Before making your first API call, ensure the following are in place:

1. Get your API key — Generate one from the Advance dashboard under Settings > API Keys.
2. Set up bank accounts — Advance-managed accounts (transitory, operational, fiduciary) are configured during onboarding. See Bank Accounts.
3. Register external accounts — Add the bank accounts where producer commissions and market premiums will be sent. See External Accounts.
4. Create at least one market — Markets represent the insurance carriers your agency works with. See Markets.

Your First Plan

Once your environment is configured, the typical flow to collect a premium is:

1. Create an insured — POST /v1/insured with the customer's name and contact details. See Insureds.
2. Create a plan — POST /v1/plans with the insured, policies, and market. This generates an invoice and a payment link. See Plans.
3. Send the payment link — Share the payment_url from the plan response with your customer, or configure Advance to email it automatically.
4. Monitor payment — Poll GET /v1/plans/{plan_id} to check collection status, or configure Webhooks to receive real-time notifications.

# 1. Create an insured
curl -X POST "https://api.sandbox.advancehq.com/v1/insured" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "insured_name": "ABC Manufacturing Inc",
    "email_primary": "[email protected]"
  }'

# 2. Create a plan with one policy
curl -X POST "https://api.sandbox.advancehq.com/v1/plans" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "insured_id": "ins_abc123",
    "payment_due": "2025-03-15T00:00:00Z",
    "status": "open",
    "policies": [
      {
        "policy_name": "General Liability",
        "policy_number": "GL-2025-001",
        "market_id": "mkt_xyz789",
        "effective_date": "2025-03-01T00:00:00Z",
        "expiration_date": "2026-03-01T00:00:00Z",
        "premium": { "name": "Premium", "amount": "8500.00" }
      }
    ]
  }'

# 3. Check plan status
curl "https://api.sandbox.advancehq.com/v1/plans/{plan_id}" \
  -H "Authorization: Bearer $API_KEY"

Core Resources