Environments

	Sandbox	Production
Base URL	https://api.dev.velocifile.ai/v1	https://api.velocifile.ai/v1
Key prefix	vf_test_	vf_live_
Data	Real catalog filings plus synthetic fixture filings	Real catalog filings
Webhook destination	Your sandbox destination	Your production destination
Test helpers	Available	Not available

The two environments are fully isolated: keys, watchers, events, deliveries, idempotency records and rate limits are separate. A key from one environment is rejected by the other.

Shared filing IDs

Filing IDs are derived from the filing itself (fil_ followed by the SERFF tracking number), so a filing has the same ID in sandbox and production and never changes. You can develop against sandbox and carry the IDs over. Watchers, events and version history are not shared. Version IDs are content fingerprints, so the same content produces the same version ID in both environments, but the version sequence and history are recorded per environment.

Sandbox fixtures

Real catalog changes cannot be produced on demand, so sandbox adds a small set of synthetic filings you can change yourself:

• Tracking numbers start with TEST-. The carriers are car_test_fixture and car_test_fixture_2.

• Fifteen fixture filings across CO and TX, product lines personal_farmowners and commercial_auto. Twelve (-001 to -003) each have two to four generated PDFs.

• Three more exercise the manifest edge cases:

  • TEST-CO-FO-004: the filing lists an attachment VelociFile does not hold, so its manifest is partial with one missing_documents entry.
  • TEST-TX-CA-004: one document is not a PDF, so its manifest answers 422 CAPABILITY_UNSUPPORTED.
  • TEST-CO-CA-004: one document is over the 100 MiB per-PDF limit, so its manifest answers 422 CAPABILITY_UNSUPPORTED.

  The last two read with source_available: false.

Test helpers

Preview

This feature is rolling out; details may change before general availability.

These routes exist in sandbox only. In production they do not exist, and the service refuses to start with them enabled.

Simulate a filing change

POST /test/filings/{filing_id}/simulate

{ "action": "amend" }

action is one of amend, correct, withdraw, move_state or move_product_line. The move actions also take a value with the new state or product line code. Only fixture filings can be simulated. The call edits the fixture and bumps its updatedAt, then returns the filing. Change detection, events and webhooks then fire exactly as they would for real data, within five minutes (change detection runs every four minutes), or at once if you call POST /test/detection:run. This lets you test a filing entering and leaving a query, an amendment and a withdrawal.

Run change detection now

POST /test/detection:run

Runs one change-detection pass over the sandbox fixture filings right away and returns { "filings_seen": 15, "events_created": 1 }. Real catalog filings are left to the scheduled pass. Only one pass runs at a time: while one is in progress (the scheduled one, which takes a few seconds every four minutes, or another call) it answers 409 CONFLICT (retryable). Wait a few seconds and retry, or let the scheduled pass pick up your change. A 409 does not count against the limit of one call per account every 30 seconds; a faster call answers 429 with Retry-After.

Test receiver

POST /test/receivers/{name}/events
GET  /test/receivers/{name}/events

The POST route is a reference webhook receiver. It authenticates by webhook signature, so the POST needs no Authorization header: the account comes from the X-Velocofile-Key-Id header, and the receiver verifies the signature with that account’s signing secret. It answers 202 for a new event or an identical duplicate, 409 for the same event_id with different content, and 401 for a bad signature. The GET route lists the receipts and does need your API key (Authorization: Bearer $VELOCIFILE_API_KEY). Point your sandbox destination at the POST route before your own receiver exists. See Webhooks.