Carriers

Carriers represent the insurance companies whose policies your agency writes. In Advance, carriers are linked to policies within plans and determine how collected premiums are routed and what commission rates apply. Full carrier management (create, update) is handled through the Advance dashboard; the public API exposes read access and product line rate management.

Product Lines and Commission Rates

A carrier's product lines represent the types of insurance they offer (e.g., "General Liability", "Auto", "Workers Comp"). Each product line carries a commission rate — the percentage of premium the agency earns from the carrier for policies written on that line.

These rates are versioned with effective dates, working the same way as producer commission rates:

• Each rate version has an effective_from and optionally an effective_to date
• When a policy is created, the rate active on the policy's effective date is locked in permanently
• New rate versions don't affect existing policies
• If an open-ended rate exists for the same product line, creating a new version automatically closes the old one

Viewing rate history

GET /v1/carriers/{carrier_id}/product-lines/history

Returns all rate versions grouped by product line name. Each group has three buckets:

• current_rate — the version active today
• scheduled_rate — a future version not yet in effect (null if none scheduled)
• historical_rates — past versions that have expired

[
  {
    "name": "Auto Insurance",
    "current_rate": {
      "product_line_id": "pl_abc",
      "commission_percentage": 15.0,
      "effective_from": "2024-01-01",
      "effective_to": "2025-05-31"
    },
    "scheduled_rate": {
      "product_line_id": "pl_def",
      "commission_percentage": 18.0,
      "effective_from": "2025-06-01",
      "effective_to": null
    },
    "historical_rates": [
      {
        "product_line_id": "pl_ghi",
        "commission_percentage": 10.0,
        "effective_from": "2023-01-01",
        "effective_to": "2023-12-31"
      }
    ]
  }
]

Setting a new rate

POST /v1/carriers/{carrier_id}/add-product-line

Provide the product line name, commission_percentage, and effective_from. Leave effective_to null for an open-ended rate. Rates are immutable once created — to change a rate, create a new version. If an open-ended rate already exists for the same name, it is automatically closed (its effective_to is set to the day before the new rate starts).

curl -X POST "https://api.advancehq.com/v1/carriers/car_abc123/add-product-line" \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "General Liability",
    "commission_percentage": 15.0,
    "effective_from": "2025-01-01"
  }'

Deleting a rate entry

DELETE /v1/carriers/{carrier_id}/product-lines/{product_line_id}

Removes a specific rate version. Returns 400 if any policies reference this product line (immutability protection). Returns 204 on success.

If you delete a future-dated rate, the predecessor rate that was automatically closed when it was created is reopened — its effective_to is reset to null, making it open-ended again.

Connecting Carriers to Plans

When creating a plan, each policy specifies a carrier_id. If you also set product_line_name on the policy, Advance automatically looks up the commission rate for that product line on the policy's effective date and applies it. This eliminates the need to manually specify commission_percentage on every policy.

Looking Up Carriers

Three ways to find a carrier:

• GET /v1/carriers — list all carriers (returns lean objects without product lines)
• GET /v1/carriers/{carrier_id} — full details including all active product line rates
• GET /v1/carriers/customer_external_id/{customer_external_id} — look up by your system's identifier

The lean list endpoint is efficient for building carrier selection dropdowns in your UI. Fetch the individual carrier when you need product line details.

The customer_external_id lookup is useful when you store carriers in your AMS by your own codes and want to find the corresponding Advance carrier without maintaining a separate ID mapping.