nfors.ai API reference

Enforcement holds (503 details.hold_reason)

POST /plate-events and POST /violations refuse to authorise enforcement when an unmatched plate cannot be proven unmatched. That refusal is a 503 upstream_unavailable with Retry-After: 30 and a details.hold_reason naming which gate held it. The reason is a fixed enum — never a provider message, plate, zone, or operator value.

{
  "error": {
    "code": "upstream_unavailable",
    "message": "A required service is temporarily unavailable. Retry later.",
    "details": { "hold_reason": "permit_mirror_stale" }
  }
}

The three reasons are not interchangeable, and only one of them makes retrying useful. Branch on the value; do not treat every 503 as the same backoff.

• live_coverage_recheck_failed — we called your live coverage API, it reported the plate as covered, and our own canonical matcher could not reproduce that from the permit we hold. The two systems disagree. Actionable by you: reconcile the session your API reported against the permit you have pushed or we have polled for that plate, zone, and instant. Retrying without changing anything reproduces the same disagreement.
• permit_mirror_stale— no live answer was available and the permit data we mirror for that zone is too old to enforce against, so an empty match cannot be trusted to mean “no permit”. Retrying will not help until your sync catches up. Only you can resolve it: resume the permit feed, or fix the failing provider connection. Re-sending the same event on a short timer produces one 503 per attempt and changes nothing.
• live_coverage_not_persisted — coverage was detected but our own write of it did not land, so we will not enforce against a permit we failed to record. This one is ours, it is transient, and retry is reasonable — honour Retry-After and re-send the same body and external_id.

Why the distinction is published at all: one plate was re-sent every four minutes for 92 hours — 1,357 events — because the caller could not tell that retrying was pointless. The reason is also recorded on your /developer/errors row as a permit_hold:<reason> field-error label, so the same distinction is queryable after the fact.

hold_reason is reused by two other, separate vocabularies, so match on the value and ignore what you do not recognise rather than assuming a 503 is always an enforcement hold. Plate-identity resolution publishes hold_reason: runtime_failure at 503 (with Retry-After: 5) and identity_review_required, effective_identity_invalid, invalid_jurisdiction, or invalid_operation at 409; permit preview publishes permit_identity_ambiguous at 409. None of those are permit-safety holds, and an unrecognised reason is dropped rather than echoed.

Create

curl -s -X POST https://nfors.ai/api/v1/locations \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "North Pensacola Campus",
    "external_id": "lp-campus-42",
    "address": "25 W Government St, Pensacola, FL 32502",
    "timezone": "America/Chicago"
  }'

List, fetch, update, delete

GET    https://nfors.ai/api/v1/locations
GET    https://nfors.ai/api/v1/locations/{id}
PATCH  https://nfors.ai/api/v1/locations/{id}
DELETE https://nfors.ai/api/v1/locations/{id}

Deleting a location is safe: zones currently assigned here have their location_id cleared but are not deleted.

Location object

{
  "id": "uuid",
  "name": "North Pensacola Campus",
  "external_id": "lp-campus-42" | null,
  "address": "..." | null,
  "timezone": "America/Chicago" | null,   // IANA
  "notes": "..." | null,
  "enforcement_hours": {...} | null,       // P2.1 default; null = no default
  "operating_hours":   {...} | null,
  "max_capacity":      40   | null,
  "created_at": "ISO 8601",
  "updated_at": "ISO 8601"
}

The three override fields feed every zone assigned to this location whose own column is null. Zone-level values win over location defaults — see effective_* on GET /zones for the resolved shape.

Create

curl -s -X POST https://nfors.ai/api/v1/zone-mappings \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_external_id": "lot-A",
    "provider": "PARKMOBILE",
    "source_zone_code": "12345"
  }'

source_zone_code is unique per (operator_id, provider) — one upstream code can only point to one nfors zone. Each nfors zone can likewise have only one mapping for a given provider, matching the integration-card model in the dashboard.

List, fetch, update, delete

# list (filters: zone_id, provider, limit, cursor)
GET    https://nfors.ai/api/v1/zone-mappings?provider=PARKMOBILE

GET    https://nfors.ai/api/v1/zone-mappings/{id}
PATCH  https://nfors.ai/api/v1/zone-mappings/{id}
DELETE https://nfors.ai/api/v1/zone-mappings/{id}

Zone mapping object

{
  "id": "uuid",
  "zone_id": "uuid",
  "provider": "PARKMOBILE" | "PARKLYNC" | "LEVEL" | "SPOTHERO" |
              "PAYBYPHONE" | "FLOWBIRD" | "PARKINGBOSS" |
              "PASSPORT" | "HONK" | "T2",
  "source_zone_code": "12345",
  "config": {},
  "created_at": "ISO 8601",
  "updated_at": "ISO 8601"
}

These are provider-scoped routing identities. LEVEL supports both push and pull workflows and uses mappings too. MANUAL and DASHBOARD are local sources, so they have no provider zone namespace.

Source intent and effective plate identity

Permit and whitelist writes treat plate_number and plate_stateas source intent. nfors retains that submitted identity in an immutable resolution receipt, then returns the effective matching identity in the response’s top-level plate_number and plate_state. A deterministic, published rule can therefore rewrite a plate; a merely plausible alternative never replaces it.

You may supply plate_identity_context with any of plate_class, issuer_product_code, design_code, serialized_segment, and plate_issue_date (YYYY-MM-DD). Do not send provenance: nfors assigns it from the authenticated workflow, and omitted facts remain unknown rather than being inferred from a default.

# Source intent
{
  "plate_number": "FL-O0",
  "plate_state": "FL",
  "plate_identity_context": {
    "plate_class": "personalized",
    "serialized_segment": "personalized_message"
  }
}

# The parent response carries the effective identity plus safe metadata only.
{
  "plate_number": "FL00",
  "plate_state": "FL",
  "plate_identity": {
    "outcome": "rewritten",
    "explanation_code": "...",
    "receipt_reference": "opaque-reference"
  }
}

plate_identity.outcome is one of unchanged, rewritten, candidate_only, insufficient_context, ambiguous_scope, rules_unavailable, or legacy_unversioned. Candidate, insufficient-context, ambiguous, and unavailable outcomes are suppressive: they cannot authorize a rewrite or let an alternative justify a money action, and the source identity remains effective. explanation_code is a safe machine-readable reason and can be null on a historical parent projection; receipt_reference is opaque and can be null for a legacy row. Responses do not include candidate values, source/effective pairs, rule IDs, or provenance.

Idempotency is identity-safe. Reusing the same (provider, external_id) with a changed source plate or scope is a conflict (409 for a single write; a rejected row in bulk). Validity-window, lifecycle, and metadata updates retain the original receipt.

The first writer channel also owns that natural key. A provider-managed row cannot be taken over implicitly by an API writer (or vice versa), even with the same plate: the write is a 409 until an explicit, audited channel migration is performed.

Ordinary updates cannot add, remove, or replace an external_id. They also cannot change provider on an externally keyed row. Those changes alter receipt ownership and require the same audited handoff; an ID-owned row without an external key may re-resolve provider context normally.

Extending a receipt-backed permit or whitelist validity window commits the parent change and its receipt-retention extension atomically; it does not create or replace the original receipt. A receipt-backed row with an external_id cannot be hard-deleted. DELETE returns 409 with details.schema: coverage_parent_delete and a replacement of end_permit or expire_whitelist. Use the corresponding lifecycle update through PATCH. Legacy and ID-owned delete behavior is unchanged.

Upsert a permit

curl -s -X POST https://nfors.ai/api/v1/permits \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_external_id": "lot-A",
    "plate_number": "ABC1234",
    "plate_state": "FL",
    "valid_from": "2026-04-14T00:00:00Z",
    "valid_to":   "2026-05-14T00:00:00Z",
    "permit_type": "monthly",
    "provider": "LEVEL",
    "channel": "SUBSCRIPTION",
    "space_number": "A12",
    "external_id": "lp-44817",
    "metadata": { "tenant": "Unit 204" }
  }'

If external_id is provided, the request is idempotent — sending the same external_id again updates the existing permit instead of creating a duplicate. Omit external_id for one-off inserts.

Bulk upsert (up to 1000 per request)

curl -s -X POST https://nfors.ai/api/v1/permits/bulk \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "permits": [
      { "zone_id": "...", "plate_number": "AAA111", "plate_state": "FL",
        "valid_from": "...", "valid_to": "...", "external_id": "p-1" },
      { "zone_id": "...", "plate_number": "BBB222", "plate_state": "FL",
        "valid_from": "...", "valid_to": "...", "external_id": "p-2" }
    ]
  }'

# {
#   "data": [ /* created/updated permit objects */ ],
#   "accepted_count": 1,
#   "rejected": [
#     { "index": 1, "error": "Plate identity could not be resolved." }
#   ],
#   "results": [
#     { "index": 0, "status": "accepted", "outcome": "unchanged",
#       "explanation_code": "...", "receipt_reference": "opaque-reference" },
#     { "index": 1, "status": "rejected",
#       "error": "Plate identity could not be resolved." }
#   ]
# }

Bulk writes support partial success. results has one index-preserving entry per submitted row. Accepted entries expose only outcome, explanation_code, and receipt_reference; rejected entries expose one safe error. The compatibility data and rejectedarrays remain available. Retry only rejected indices after correcting the input. The whole request only 4xx’s when nothing was valid.

List, fetch, update, delete

# list (filters: plate, state, zone_id, active_at, external_id,
#        provider, channel, space_number, status, limit, cursor)
GET https://nfors.ai/api/v1/permits?active_at=2026-04-14T18:00:00Z&provider=PARKMOBILE&limit=100

GET    https://nfors.ai/api/v1/permits/{id}
PATCH  https://nfors.ai/api/v1/permits/{id}
DELETE https://nfors.ai/api/v1/permits/{id}

Permit object

{
  "id": "uuid",
  "zone_id": "uuid",
  "plate_number": "ABC1234",     // effective matching identity
  "plate_state": "FL",            // effective issuing jurisdiction
  "plate_identity": {
    "outcome": "unchanged" | "rewritten" | "candidate_only" |
               "insufficient_context" | "ambiguous_scope" |
               "rules_unavailable" | "legacy_unversioned",
    "explanation_code": "machine-readable-reason" | null,
    "receipt_reference": "opaque-reference" | null
  },
  "country": "US",                // ISO-3166 alpha-2, defaults to "US"
  "make_model": "Honda Civic" | null,
  "valid_from": "ISO 8601",
  "valid_to":   "ISO 8601",
  "provider": "PARKMOBILE" | "PARKLYNC" | "SPOTHERO" | "PAYBYPHONE" |
              "FLOWBIRD" | "PARKINGBOSS" | "PASSPORT" | "HONK" |
              "T2" | "LEVEL" | "MANUAL" | "DASHBOARD",
  "channel": "SUBSCRIPTION" | "PM_SESSION" | "GUESTPAY" | ... | null,
  "space_number": "A12" | null,
  "status": "ACTIVE" | "ENDED" | "VOIDED" | "SUPERSEDED",
  "voided_reason": "REFUND" | "DISPUTE" | "ADMIN_VOID" | "PROVIDER_VOID" | "REPLACED" | null,
  "ended_at": "ISO 8601" | null,  // set when observed terminated; null while ACTIVE
  "supersedes_permit_id": "uuid" | null,
  "source": "PMS" | null,         // deprecated — prefer provider/channel
  "permit_type": "monthly" | "hourly" | "event" | "employee" | "visitor" | "resident" | "other" | null,
  "metadata": { ... },
  "external_id": "your-id" | null,
  "created_via": "api" | "dashboard",
  "created_at": "ISO 8601",
  "updated_at": "ISO 8601"
}

Provider + channel split the legacy free-form source into two orthogonal fields. A Parkmobile hourly session and a Level Parking GuestPay session are different providers but similar channels(both transient paid). Separating them lets you query “all Parkmobile activity” independently of “all transient-paid activity.”

Space number lets you attach permits to a specific numbered stall in a lot. Match-time lookups can filter to the exact space or fall back to zone-wide permits.

Idempotency is scoped to (operator_id, provider, external_id). Parkmobile “12345” and Passport “12345” are distinct rows — they do not collide.

Legacy source is still accepted on write and will be translated to provider/channel when recognisable. The source field is deprecated and will be removed in a future major version.

Upsert across specific zones

curl -s -X POST https://nfors.ai/api/v1/whitelist \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_ids": ["zone-1-uuid", "zone-2-uuid"],
    "plate_number": "VIP100",
    "plate_state": "FL",
    "valid_to": "2027-01-01T00:00:00Z",
    "permit_type": "employee",
    "external_id": "hrms-3319"
  }'

Choose one zone identity

Provide exactly one of zone_ids, zone_external_ids, zone_source_codes, or all_zones: true. Operator aliases in zone_external_ids must all resolve. Provider-owned zone_source_codes require an explicit provider; nfors resolves them through that provider’s zone mappings and applies the entry to the mapped subset, returning 400 only when none resolve. Provider source codes are supported by the single-entry POST /whitelist route; the bulk route does not resolve this identity form.

# Operator-owned zone aliases
{ "zone_external_ids": ["LOT-A", "LOT-B"], ... }

# Provider-owned zone codes
{
  "provider": "LEVEL",
  "zone_source_codes": ["10001", "10002"],
  ...
}

Upsert across every zone

curl -s -X POST https://nfors.ai/api/v1/whitelist \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "all_zones": true,
    "plate_number": "OWNER1",
    "plate_state": "FL"
  }'

Exactly one zone-identity form or all_zones: true must be provided. valid_from / valid_to are both optional; omit both for a permanent entry.

Bulk + CRUD

POST   https://nfors.ai/api/v1/whitelist/bulk   # up to 1000 entries
GET    https://nfors.ai/api/v1/whitelist         # filters: plate, state, external_id,
                                 #   provider, channel
GET    https://nfors.ai/api/v1/whitelist/{id}
PATCH  https://nfors.ai/api/v1/whitelist/{id}
DELETE https://nfors.ai/api/v1/whitelist/{id}

Whitelist object

{
  "id": "uuid",
  "zone_ids": ["uuid", ...] | null,   // null = applies to every zone
  "all_zones": boolean,
  "plate_number": "VIP100",
  "plate_state": "FL",
  "plate_identity": {
    "outcome": "unchanged" | "rewritten" | "candidate_only" |
               "insufficient_context" | "ambiguous_scope" |
               "rules_unavailable" | "legacy_unversioned",
    "explanation_code": "machine-readable-reason" | null,
    "receipt_reference": "opaque-reference" | null
  },
  "valid_from": "ISO 8601" | null,
  "valid_to":   "ISO 8601" | null,
  "provider": "PARKMOBILE" | "PARKLYNC" | "SPOTHERO" | "PAYBYPHONE" |
              "FLOWBIRD" | "PARKINGBOSS" | "PASSPORT" | "HONK" |
              "T2" | "LEVEL" | "MANUAL" | "DASHBOARD",
  "channel": "EMPLOYEE" | "OWNER" | ... | null,
  "source": "legacy-hint" | null,     // deprecated — prefer provider/channel
  "permit_type": "employee" | "visitor" | ... | null,
  "metadata": { ... },
  "external_id": "your-id" | null,
  "created_via": "api" | "dashboard",
  "created_at": "ISO 8601",
  "updated_at": "ISO 8601"
}

Whitelist idempotency is scoped to (operator_id, provider, external_id) — same as permits — so two providers can both push the same upstream ID without colliding.

Reusing that key with a different source plate or zone scope returns 409. Validity, lifecycle, and metadata-only changes update the existing entry while retaining its original plate-identity receipt.

Two ways to attach images

Supply either file_ids (from POST /files) or image_urls (publicly fetchable HTTPS URLs — often signed URLs from your LPR storage). Mix and match up to 5 images total. URL fetches reject redirects and any host that resolves to a private IP.

End-to-end LPR submission

# 1. Upload the plate close-up and wide shot.
FILE1=$(curl -s -X POST https://nfors.ai/api/v1/files \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -F "file=@plate.jpg" | jq -r .data.id)
FILE2=$(curl -s -X POST https://nfors.ai/api/v1/files \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -F "file=@vehicle.jpg" | jq -r .data.id)

# 2. Create the violation.
curl -X POST https://nfors.ai/api/v1/violations \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_id": "2f27d3f2-...",
    "violation_reason_id": "a1b2c3d4-...",
    "notice_type": "charge",
    "plate_number": "ABC1234",
    "plate_state": "FL",
    "latitude": 30.4213,
    "longitude": -87.2169,
    "issued_at": "2026-04-15T14:32:07Z",
    "source": "api_lpr",
    "provider": "LEVEL",
    "channel": "FIELD_LPR",
    "external_id": "lpr-batch-7781",
    "notes": "Vehicle in fire lane",
    "metadata": {
      "camera_id": "lot-a-north",
      "lpr_confidence": 0.982,
      "detection_time": "2026-04-15T14:32:04Z",
      "make_model": "Toyota Camry / silver"
    },
    "file_ids": ["'"$FILE1"'", "'"$FILE2"'"]
  }'

About the three similar-sounding fields:source is the capture method (api_lpr | api_manual | api); provider is which system originated the data (your operator code or an upstream integration); channel is what kind of interaction it is (e.g. FIELD_LPR, GATE_LPR). Both provider and channel are optional; sensible defaults apply (MANUAL, null). Violations idempotency is scoped to (operator_id, provider, external_id) so two upstream systems can both reuse the same ID.

Or skip the upload step with image_urls

curl -X POST https://nfors.ai/api/v1/violations \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_id": "...",
    "violation_reason_id": "...",
    "plate_number": "ABC1234",
    "plate_state": "FL",
    "external_id": "lpr-read-7781",
    "latitude": 30.4213,
    "longitude": -87.2169,
    "image_urls": [
      "https://lpr.level-parking.com/signed/plate-7781.jpg",
      "https://lpr.level-parking.com/signed/wide-7781.jpg"
    ]
  }'

URLs must be https://, return JPEG, PNG, WebP, HEIC, or HEIF content of at most 10 MB, and not redirect. nfors verifies the file signature rather than trusting the declared content-type, then stores the bytes.

Idempotency

external_id remains optional for v1 compatibility, but integrations should always supply a durable, unique value. It prevents a replay from creating a second notice and lets nfors verify or repair manifest-backed image attachment and its deterministic webhook outbox entry. Successful replays return the original notice with idempotent_replay: true. Requests without external_id cannot be correlated after response loss. Collection enqueue and the overall multi-table ingest are still not one atomic database transaction. A replay of a legacy notice whose original request or frozen collection intent cannot be verified returns 409 with details.ingest_state set to legacy_request_unverifiable or legacy_collection_intent_unverifiable, plus repairable_automatically: false. The response does not disclose the existing notice ID. A validated retry whose decision fields differ instead returns details.ingest_state="request_mismatch". If a manifest-backed replay cannot complete evidence verification or repair, the response instead carries details.ingest_state="evidence_incomplete"; follow the HTTP status and Retry-After semantics without assuming a second notice should be created.

Permit-match guard

If the plate has an active permit or whitelist entry in the zone at issued_at, the POST returns 409 conflict with a closed preview containing reason="active_permit_match", a bounded match_count, and the match-tier enum when available. It does not disclose a permit, whitelist, plate, or customer record. Resend with permit_override_reasonto issue anyway (recorded in the charge’s notes for audit).

When the plate matches nothing, nfors additionally proves the miss is trustworthy before issuing. If it cannot, the POST returns 503 upstream_unavailable with a details.hold_reason and no charge is created. Two of the three reasons are yours to clear and are not fixed by retrying — see Enforcement holds.

Response

{
  "data": {
    "id": "...", "violation_number": "NF-2026-000834",
    "notice_type": "charge",
    "status": "issued", "source": "api_lpr", "external_id": "lpr-batch-7781",
    "plate_number": "ABC1234", "plate_state": "FL",
    "base_charge_amount": 7500, "total_amount": 7500,
    "latitude": 30.4213, "longitude": -87.2169,
    "issued_at": "2026-04-15T14:32:07Z",
    "metadata": { "camera_id": "...", "lpr_confidence": 0.982, ... },
    "images": [
      { "storage_path": "...", "url": "https://signed.supabase.co/..." }
    ]
  }
}

Signed image URLs expire in ~1 hour. Use GET /violations/{id} to get a fresh set.

Same-stay suppression

A monetary Level LPR request that collides with an existing protected same-stay claim does not create a second charge. It returns HTTP 200 with this redacted terminal outcome; callers must handle it as success, not retry it as an issuance failure:

{
  "data": null,
  "decision": "no_action",
  "decision_reason": "existing_charge_same_stay"
}

Fetch a current violation

GET /violations/{id} uses the read scope and is tenant-scoped; an unknown or other-operator ID returns 404 not_found. The response refreshes expiring signed image URLs and returns the current notice, amount, delivery, status, metadata, and image fields.

curl -s https://nfors.ai/api/v1/violations/{id} \
  -H "Authorization: Bearer $NFORS_API_KEY"

Batch lookup (up to 200 plates per request)

curl -s -X POST https://nfors.ai/api/v1/permit-match/batch \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "at": "2026-04-15T19:00:00Z",
    "grace_seconds": 30,
    "queries": [
      { "plate": "ABC1234", "state": "FL", "zone_external_id": "lot-A" },
      { "plate": "XYZ7890", "state": "FL", "zone_external_id": "lot-A", "space_number": "A12" }
    ]
  }'

# {
#   "count": 2,
#   "valid_count": 1,
#   "error_count": 0,
#   "results": [
#     { "index": 0, "valid": true,  "matches": [{ "kind": "permit", "provider": "PARKMOBILE", ... }],
#       "stacked_prefix": null, "error": null, "error_code": null },
#     { "index": 1, "valid": false, "matches": [],
#       "stacked_prefix": null, "error": null, "error_code": null }
#   ]
# }

Top-level at and grace_seconds apply as defaults; any query can override its own. Unknown zone_id or zone_external_id does not fail the whole request — the offending row carries an error string and others proceed. Its stable companion error_code is invalid_request, not_found, upstream_unavailable, or permit_identity_ambiguous; both fields are null when the row was evaluated normally. A successful stacked fallback carries the same { observed_plate, matched_core } in stacked_prefix.

Event envelope

{
  "type": "violation.issued",
  "created_at": "2026-04-14T18:42:03.004Z",
  "data": { "violation_id": "...", "violation_number": "NF-2026-000042", "zone_id": "...", "plate_number": "ABC1234", "plate_state": "FL" }
}

Signature verification

Every delivery includes a nfors-signature header in the form t=<unix-seconds>,v1=<hex-hmac>. Compute HMAC-SHA256 of <t>.<raw-body>with your endpoint’s signing secret (whsec_..., shown once at creation) and compare against v1.

// Node 20+
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map(p => {
    const i = p.indexOf('='); return [p.slice(0, i), p.slice(i + 1)];
  }));
  const t = Number(parts.t);
  if (Math.abs(Date.now()/1000 - t) > 300) return false;  // 5-min replay window
  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const got = Buffer.from(parts.v1, 'hex');
  return got.length === expected.length && timingSafeEqual(expected, got);
}

Read the raw request body before JSON-parsing for verification to succeed byte-for-byte.

Event types

• permit.created / permit.updated / permit.deleted
• whitelist.created / whitelist.updated / whitelist.deleted
• violation.issued — a new parking charge was issued
• warning.issued — a non-financial parking warning was issued; it is never sent as violation.issued
• notice.delivered — an agent confirmed the printed notice or reusable QR card was placed on the vehicle
• violation.voided — a charge was voided; newly queued payloads add nullable provider, zone_source_code, canonical zone_id, and legacy zone_external_id without changing existing correlation fields
• violation.reduced — a supervisor reduced a charge’s amount
• violation.paid — a charge was paid in full, by Stripe Checkout or a recorded off-platform payment
• payment.succeeded — a payment was received: Stripe Checkout, or an operator-recorded check / money order / cash. A partial off-platform payment fires this without violation.paid
• payment.refunded — refund processed. Payload carries refund_reason: dispute_approved | duplicate_payment | operator_error | provider_error | goodwill | other | null (unknown; set it by passing metadata.reason on stripe.refunds.create). A reversed off-platform payment also fires this, with reversed: true.
• dispute.created — parker submitted a dispute
• dispute.resolved — dispute approved or denied
• violation.evaluated — an enqueued /plate-events decision event (issued / no-action / alert-logged), with a match_reasoning block; consumers must not use it as the sole record of the synchronous API decision
• violation.corrected — a supervisor corrected a charge’s plate or vehicle; payload carries fields_changed, plate_changed, void_cascaded
• queue.opened / queue.ready / queue.resolved — grace-period queue lifecycle; payloads always carry canonical zone_id and LPR-origin rows also carry nullable provider + zone_source_code. Level correlates by provider/source first, canonical UUID second, and the legacy alias only as a temporary fallback. resolved carries resolution.kind: violation / paid / departed / void / expired
• blockout.created / blockout.cancelled — an enforcement block-out was scheduled or cancelled

Every event name above, including violation.corrected, is valid in a registration’s events array. Use * to subscribe to every current and future event type.

Register endpoints via the API

Manage endpoints programmatically instead of the dashboard. POST /webhook-endpoints returns { id, signing_secret } on a fresh create (the secret is shown once); a repeat of the same (operator, url) returns { id, idempotent: true } with no secret. DELETE /webhook-endpoints/{id} deregisters it (tenant-scoped 404; cascades pending deliveries). Rotate a secret with a DELETE + POST cycle.

curl -X POST https://nfors.ai/api/v1/webhook-endpoints \
  -H "Authorization: Bearer $NFORS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Production decisions",
    "url": "https://example.com/hooks/nfors",
    "events": ["violation.evaluated", "violation.corrected"]
  }'

Redelivery

Retained delivery records, including succeeded, failed, and abandoned attempts, are available for operational review under Settings → Webhooks. Click Redeliver on an available row to retry.

Request

POST /api/v1/reports/execute
Authorization: Bearer nfors_live_...
Content-Type: application/json

{
  "subject": "violations",
  "filters": {
    "date_range": { "kind": "preset", "preset": "last_30d" },
    "zone_ids": ["<zone-uuid>"]
  },
  "group_by": "agent",
  "metric": "count"
}

Subjects, group-bys, and metrics

• violations — group by day/week/month/agent/zone/location/reason/status/plate_state/hour_of_day/day_of_week/none; metrics: count/sum_total/sum_base/sum_late_fee/paid_count/paid_rate/photo_coverage_rate
• payments — group by day/week/month/status/refund_reason/zone/location/agent/none; metrics: count/sum_total/sum_platform/sum_operator/sum_refund
• check_ins — group by day/week/month/agent/zone/hour_of_day/day_of_week/none; metrics: count/distinct_zones/distinct_agents
• disputes — group by day/week/month/status/reviewer/zone/agent/none; metrics: count/approval_rate/denial_rate/avg_resolution_days/on_time_rate
• collections — group by day/week/month/status/source/zone/agent/none; metrics: count/cure_rate/letters_per_case/mailed_avg

Date range

Either a preset (last_7d, last_30d, last_90d, month_to_date, quarter_to_date, year_to_date) or a custom ISO-8601 pair:

"date_range": {
  "kind": "custom",
  "from": "2026-04-01T00:00:00.000Z",
  "to":   "2026-04-30T23:59:59.999Z"
}

Response

{
  "rows": [
    { "dim_key": "<agent-uuid>", "dim_label": "Alex Officer", "metric_value": 47 },
    { "dim_key": "<agent-uuid>", "dim_label": "Priya Lopez", "metric_value": 31 }
  ],
  "from":   "2026-03-24T00:00:00.000Z",
  "to":     "2026-04-23T23:59:59.999Z",
  "metric": { "key": "count", "label": "Violations", "shape": "count" },
  "query":  { ...echoed back for audit/caching... }
}

rows is sorted by dim_key. Money metrics return cents (integer). Percent metrics return a 0..1 ratio. The metric.shape field tells you which formatter to apply.

Scope & rate limit

Scope is derived from the API key — the operator_id in the body cannot widen it. Counts against the read rate budget (500/s default per key; overridable per-key via rate_limit_per_sec_reads).