Valley Insurance

Valley Insurance Partner API

The Partner API lets your systems price surplus-lines insurance and submit filings to Valley Insurance without a human in the loop.

Two terms come up throughout these docs:

  • Surplus lines: insurance placed with a carrier that isn't licensed in the insured's state, used when the standard (admitted) market won't cover a risk. States require this coverage to be reported and taxed through a filing.
  • Filing: the paperwork you submit to Valley Insurance after a policy is bound, so we can report it to the state and collect the required taxes and fees.
Base URL and auth

Every request goes to https://api.valleyinsllc.com/api/v1 and carries a PartnerKey header. See Authentication for details.

The two jobs

Almost everything a partner does falls into one of two tasks:

JobWhat it answersStart here
Price"What would this policy cost in taxes and fees?"Price a policy
File"Submit this bound policy as an official filing."Submit a filing
Which recipe do you need?
  • Just need a number to quote a client, before anything is bound? Go to Price a policy. One call, no documents required.
  • Ready to submit a bound policy? Go to Submit a filing. It covers finding the right state, uploading documents, creating the filing, and tracking its status.
  • Need to know what a state requires or what it charges before you quote a client? See State pricing and requirements.

The filing lifecycle

A filing moves through five stages once you decide to submit one:

  1. Price it. Call POST /partner/calculate with the filing type, state, and premium to get the filing fee, tax, and total. See Price a policy for the full request and response.
  2. Look up the state's required documents. Call GET /partner/filing-states and read descriptionNb/descriptionEd, an HTML requirements checklist, and filesNb/filesEd, the list of documents to gather, for whichever pair matches your filingType. Full breakdown in State pricing and requirements. You can only file in the states listed in enabledStates on GET /partner/me; contact gina@valleyinsllc.com to request access to others.
  3. Upload each document. Call POST /partner/upload-user-file to get a signed URL, then PUT the file bytes to it. Covered in Submit a filing, step 2.
  4. Create the filing. Call POST /partner/create-filing with the policy details and the uploaded files' paths. This returns the filing record. See Submit a filing, step 3.
  5. Track it. Call GET /partner/{id} any time to check the filing's status. Lost the id? GET /partner/filings lists your own filings, paginated. See Submit a filing, step 4.

Full walkthrough with request and response bodies: Submit a filing. Want to run the whole thing without writing any code? See Run the whole flow below.

Run the whole flow (one script)

Prefer to see it work before you write any code? Download a single self-contained script that runs every step above against the real API and prints friendly output along the way: fetch your account, price a policy, look up a state's requirements, upload a document, create a filing, and track it. Pick whichever you have available, Node or a shell.

Download try-valley-partner-api.mjs

RequirementsNode.js 18 or later. No npm install, it only uses the built-in fetch.
Run itexport PARTNER_KEY=your-key-here then node try-valley-partner-api.mjs

Download try-valley-partner-api.sh

Requirementsbash, curl, and jq. No Node needed.
Run itchmod +x try-valley-partner-api.sh, export PARTNER_KEY=your-key-here, then ./try-valley-partner-api.sh
This creates a real filing

Running this script creates a real filing in your account, it isn't a dry run or a sandbox. It uses obvious TEST values (a policy number prefixed TEST- and an insured name prefixed TEST -), so you can find it afterward and delete it if you don't want to keep it.

See it referenced again in context in Submit a filing.

What's next

Need a key? Contact Gina Doyle at gina@valleyinsllc.com.