Filings and versions

Identifiers

Object	Format	Notes
Filing	fil_<SERFF tracking number>	Derived from the filing. Never changes. The same in sandbox and production.
Version	fv_<32 hex characters>	A content fingerprint. The same content always gives the same ID.
Document	doc_<id>	Stable for a source document.
Carrier	car_<company group code>	The filing’s company group. naic_company_code can be null.
Watcher, event, request	wch_..., evt_..., req_...	Random.

Product line, filing type and status codes are stable lowercase slugs. Get the full dictionaries from GET /taxonomies.

What a version is

VelociFile computes a filing’s current version when you read it. The version covers the filing’s normalized metadata (tracking number, carrier, state, product line and name, filing type, status, filed date, effective date) and the identity of its current documents (document ID, file name and storage path, excluding summary rows). The fingerprint is the SHA-256 of that content, and the version ID is fv_ plus its first 32 hex characters.

The version registry

VelociFile does not copy the catalog, so it cannot reconstruct a filing’s whole past. Instead it keeps a registry that records a version only when it hands that version to you or when a watcher observes it. The registry holds, for each version:

• the version ID and filing ID
• version_sequence, a per-filing integer that counts up from 1
• previous_version_id
• change_kind: initial, amendment, source_correction, metadata_correction or withdrawal
• a metadata snapshot, observed_at, source_available, and manifest_sha256 once a manifest exists

initial means the first version VelociFile served for that filing. It is not necessarily the first version the filing ever had. See deviation 1.

change_kind between consecutive versions follows this order: withdrawal when the status becomes withdrawn; source_correction when only the document set or document bytes changed; metadata_correction when only metadata changed and no disposition or amendment moved; otherwise amendment.

curl -sS --fail-with-body "https://api.dev.velocifile.ai/v1/filings/$VF_FILING_ID/versions?limit=10" \
  -H "Authorization: Bearer $VELOCIFILE_API_KEY"

Current version only for source material

Version metadata stays readable for every version in the registry. Manifests and PDFs exist only for the filing’s current version. Asking for either on an older version answers:

{
  "error": {
    "code": "VERSION_SUPERSEDED",
    "message": "This filing version has been superseded. Read the filing again for its latest version.",
    "request_id": "req_...",
    "retryable": false
  }
}

with status 410. Read the filing, take its latest_version_id, and ask again. Store the manifest and PDFs you need on your side, because VelociFile will not serve them for a superseded version.

The bytes behind a version ID do not change while it is current. If a source PDF is overwritten in place, VelociFile registers a new version with change kind source_correction, and the old one becomes superseded.

Filings without source documents

A filing whose current version has no PDFs, or only summary rows, is returned normally with source_available: false on the filing and the version, and manifest_sha256: null on the version. Requesting its manifest answers 404 SOURCE_UNAVAILABLE.

Dates that are not dates

Some source records hold an effective date that is not a valid date. Those filings return effective_date: null and never match a search that has effective_from or effective_to.

Filters

Unknown state, product line, carrier, filing type or status codes answer 400 UNSUPPORTED_FILTER. A search never widens silently. effective_from later than effective_to answers 400 INVALID_REQUEST.