Quickstart

This page runs one search against the sandbox. You need a sandbox key (it starts with vf_test_). Export it as an environment variable so it never lands in source control.

export VELOCIFILE_API_KEY="vf_test_..."

The request asks for Texas commercial auto filings. states and product_lines are required in every filing query. Unknown codes are rejected, so take codes from GET /taxonomies.

curl

curl -sS --fail-with-body https://api.dev.velocifile.ai/v1/filings/search \
  -H "Authorization: Bearer $VELOCIFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": {"states": ["TX"], "product_lines": ["commercial_auto"]}, "limit": 5}'

Python

import os

import httpx

BASE = "https://api.dev.velocifile.ai/v1"
headers = {"Authorization": f"Bearer {os.environ['VELOCIFILE_API_KEY']}"}

response = httpx.post(
    f"{BASE}/filings/search",
    headers=headers,
    json={"query": {"states": ["TX"], "product_lines": ["commercial_auto"]}, "limit": 5},
    timeout=30,
)
response.raise_for_status()
page = response.json()

for filing in page["items"]:
    print(filing["filing_id"], filing["state"], filing["product_name"], filing["latest_version_id"])
print("next_cursor:", page["next_cursor"])

TypeScript

const BASE = "https://api.dev.velocifile.ai/v1";
const key = process.env.VELOCIFILE_API_KEY;

const response = await fetch(`${BASE}/filings/search`, {
  method: "POST",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    query: { states: ["TX"], product_lines: ["commercial_auto"] },
    limit: 5,
  }),
});
if (!response.ok) throw new Error(`${response.status} ${await response.text()}`);
const page = await response.json();

for (const filing of page.items) {
  console.log(filing.filing_id, filing.state, filing.product_name, filing.latest_version_id);
}
console.log("next_cursor:", page.next_cursor);

What comes back

{
  "taxonomy_version": "taxonomy_1",
  "snapshot_at": "2026-10-22T16:00:00Z",
  "items": [
    {
      "filing_id": "fil_ABCD-123456789",
      "tracking_number": "ABCD-123456789",
      "carrier": { "carrier_id": "car_1234", "name": "Example Carrier Group", "naic_company_code": null },
      "state": "TX",
      "product_line": "commercial_auto",
      "product_name": "Example Commercial Auto Program",
      "filing_type": "rate_and_form",
      "status": "approved",
      "latest_version_id": "fv_0a1b2c3d4e5f60718293a4b5c6d7e8f9",
      "latest_version_sequence": 1,
      "effective_date": "2026-10-01",
      "updated_at": "2026-10-20T00:00:00Z",
      "source_available": true
    }
  ],
  "next_cursor": null
}

Values above are illustrative. next_cursor is null on the last page. Otherwise pass it back as cursor with the same query. See Pagination.

Next steps

• Read one filing: GET /filings/{filing_id}.
• List its versions: GET /filings/{filing_id}/versions.
• Fetch the manifest and verify the PDFs: Manifests and integrity.
• Subscribe to changes: Watchers.