Read API

One call turns a license number into a booking decision. GET /api/v1/decision returns a verdict, the reasons behind it, the letter-grade evidence, the exact documents to collect for your event type, and a signed receipt for the event's compliance file. Anonymous, standard envelope.

curl "https://www.venumark.com/api/v1/decision?license_number=MFDV-7742&event_type=festival"

The verdict is one of four words. CLEAR: routine due diligence is sufficient. CONDITIONAL: usually safe to book after a look at recent inspections. REVIEW: compliance gaps, an insufficient record, or an unconfirmed license warrant review before booking. DECLINE: active concerns or a DBPR hold on record. Identify the vendor by license_number or vendor_id. Optional event_type (food-truck-night, festival, or city-event; default food-truck-night) selects the required-documents list and the matching checklist link.

Letter grades only. The numeric VMScore is not exposed on this endpoint, and the grade is withheld (verdict REVIEW) when the vendor's current DBPR license cannot be confirmed.

Signed receipt. Every decision comes with a tamper-evident receipt: an HMAC-signed record of the vendor, verdict, grade, and timestamp. Keep it with the event file. Receipts never expire, and anyone can verify one at any time, no key needed (GET with ?receipt=, or POST a JSON body {"receipt": "..."}):

curl "https://www.venumark.com/api/v1/decision/verify?receipt=$RECEIPT"

Vendor self-check. The same record, read from the vendor's side. GET /api/v1/improve is for a food truck or caterer reviewing their own record: it returns the current letter grade, the factors limiting it (ordered most severe first, each with the issue, a concrete corrective action, and an official resource: a DBPR page or a VenuMark guide), the strengths already on the record, and a free claim link so the vendor can claim their profile and track their standing. Anonymous, standard envelope. Identify the vendor by license_number or vendor_id. When a DBPR hold is active, the hold reasons on record are quoted in the top factor. Letter grades only, same as the decision endpoint.

curl "https://www.venumark.com/api/v1/improve?license_number=MFDV-7742"

Ongoing monitoring (VMScore Vendor Pro). The self-check response also carries the monitoring offer in its monitoring block: VMScore Vendor Pro, $9.99/month, puts a daily DBPR watch on the vendor's own record and emails them the moment anything changes. Requires a free VenuMark vendor account with the DBPR license claimed. Checkout happens in the browser at /api/vendor-pro/checkout, not through the API.

Badge embed. GET /api/badge/:vendorId serves an SVG badge with the vendor's letter grade (no numeric score). Drop it on a vendor roster page or event site, linked back to the vendor's public page:

<a href="https://www.venumark.com/vendor/VENDOR_ID"><img src="https://www.venumark.com/api/badge/VENDOR_ID" alt="VMScore badge" height="44"></a>

Statewide stats feed. GET /api/v1/stats/florida returns aggregate statistics across every scored Florida food truck and caterer (vendor counts, grade distribution, violation rates), recomputed from DBPR public records. The response includes a cite_as attribution line; the numbers are free to cite with that attribution.

curl "https://www.venumark.com/api/v1/stats/florida"

Every keyed request needs a Bearer token in the Authorization header. Keys are scoped to your account's data: you'll only see events you own, applications on those events, and vendor data publicly available via VMScore.

curl https://www.venumark.com/api/v1/events \
  -H "Authorization: Bearer vm_pk_xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Keys are revocable from Settings → API keys. Revoked keys stop working immediately on the next request.

60 requests per minute per key. Exceeding the limit returns HTTP 429 with anerror field naming the limit and a Retry-After header (seconds until the window resets). The anonymous endpoints are rate limited per IP instead: 60/min for search, 40/min for scorecards, same 429 shape.

Every /api/v1 endpoint returns the same envelope:

{
  "data": { ... } | [ ... ] | null,
  "meta": { ... } | null,
  "error": { "message": "..." } | null
}

On success error is null. On failure data isnull and error.message describes the issue. HTTP status codes are conventional (200/400/401/404/429/500). List endpoints are unpaginated: they return the full result set, with the row count in meta.count. The anonymous /api/vendors endpoints predate the envelope and return plain JSON (a bare array or object), with errors as {"error": "..."}.

License numbers are matched on digits only. Alphabetic prefixes and punctuation are stripped before lookup, so MFD7742, MFDV-7742, and 7742 all identify the same vendor.

List your events. Optional ?status=Published|Draft|Completed|Cancelled filter.

curl "https://www.venumark.com/api/v1/events?status=Published" \
  -H "Authorization: Bearer $VENUMARK_KEY"

Single event detail. 404 if you don't own it.

curl https://www.venumark.com/api/v1/events/00000000-0000-0000-0000-000000000000 \
  -H "Authorization: Bearer $VENUMARK_KEY"

List applications across all your events. Optional ?event_id=<uuid>to scope to one event. Each row includes the vendor's VMScore (vm_score, risk_tier, joined on the normalized license number, null when the vendor has no scored DBPR record), recorded outcome (post-event), deposit status, and any custom-question responses.

curl "https://www.venumark.com/api/v1/applications?event_id=$EVENT_ID" \
  -H "Authorization: Bearer $VENUMARK_KEY"

Vendor lookup by license number. Returns VMScore, risk tier, recommendation, violation rollup counts (12-month), and platform reliability when the vendor has applied to events on VenuMark. For itemized violation and inspection history use the anonymous scorecard endpoint below. Useful for pre-screening before sending an invite. Required: ?license_number=<MFDV-...>.

curl "https://www.venumark.com/api/v1/vendors?license_number=MFDV-7742" \
  -H "Authorization: Bearer $VENUMARK_KEY"

The public vendor database and the published-events feed are open. No account, no key. These return plain JSON rather than the envelope (except the events feed, which uses the envelope).

GET /api/vendors searches by name, prior name (aka), license number, or city. Params: q, city, limit (1-100, default 20), offset. Returns a bare array of vendor rows with 12-month rollup counts and license status flags.

curl "https://www.venumark.com/api/vendors?q=taco&limit=5"

GET /api/vendors/:id returns basic identity for one vendor: name, license, cuisine category, location.

GET /api/vendors/:id/scorecard returns the full public scorecard: letter grade, numeric risk score, 12-month rollups, itemized violations and inspections, and enriched detail plus analysis narrative when available.

curl "https://www.venumark.com/api/vendors/$VENDOR_ID/scorecard"

GET /api/v1/public/events lists Published events currently taking vendor applications, ordered by date, each with an apply_url pointing at the public event page. Optional ?city= filter (case-insensitive exact match). Standard envelope; cached at the edge for 5 minutes.

curl "https://www.venumark.com/api/v1/public/events?city=Tampa"

The /v1/ path is stable. Additive changes (new fields, new endpoints) ship without a version bump; breaking changes get a new version path. We'll email accounts with active API keys at least 90 days before any v1 deprecation.