ADAS Calibration API Integration Guide for Fleet Engineers
Fleet engineers integrating ADAS calibration intelligence need a clear contract: authentication, batch ingest, tier polling, evidence export, and shadow-mode guardrails. NADIR exposes REST routes and SDK clients in Python and TypeScript with org isolation, idempotency keys, and SLI-friendly error semantics. This guide walks through a production-safe integration sequence — from sandbox replay to HORIZON forecast hooks — without ECU reflashes or actuator commands during advisory phases.
Integration phases
Phase zero is read-only: pull tier snapshots for a pilot cohort and compare against shop records. Phase one adds batch ingest from telematics partners — hundreds of frames per request with deterministic deduplication. Phase two enables evidence export jobs for audit packets. Phase three wires Console webhooks or HORIZON theater modules for executive visibility.
Never skip shadow validation. Score every eligible VIN while dispatch rules stay fixed — validate false alert rates honestly before automation. The shadow-mode pilot guide defines week-by-week KPIs.
Start with the SDK quickstart and API reference; replay fixtures before production keys.
Authentication and org isolation
API keys are scoped to organizations. Batch ingest rejects cross-org identifiers at the persistence layer — critical when MSO partners serve multiple fleet customers. Rotate keys through Console; stale keys return 401 with stable error codes for monitoring.
Edge gateways authenticate with the same keys but should tag source=edge for SLI dashboards. Offline queues fsync locally and flush with exponential backoff — see edge patterns in telematics edge ingest.
Ingest payload expectations
Payloads carry VIN, timestamp, modality residuals or proxies, and optional geohash for cohort analytics. NADIR normalizes mixed OEM telematics without exposing competitor calibration secrets. Missing fields degrade gracefully — ingest SLIs surface completeness before tier quality suffers.
Idempotency keys prevent duplicate scoring on flaky cellular routes. Engineers should treat 409 responses as success-with-duplicate, not hard failures.
Tier polling and evidence export
Fleet schedulers poll tier endpoints or subscribe to webhooks when VINs transition to CAUTION or CRITICAL. Evidence export jobs assemble signed bundles — detection timestamps, tier transitions, shop actions, post-repair validation — documented on the evidence page.
Integrate with maintenance systems by mapping CRITICAL to hold rules only after shadow validation. The maintenance scheduling guide covers SLA language safety boards expect.
HORIZON and Console surfaces
Executives often discover NADIR through HORIZON forecast modules before engineering completes API wiring. The HORIZON walkthrough demonstrates theater views; API integration supplies the same tiers to custom BI.
Console histograms remain the operator contract surface — keep steering decks simple while data science explores engineer-grade residuals.
Observability and SLIs
Instrument ingest latency, batch acceptance rate, tier poll freshness, and evidence job completion. NADIR returns stable HTTP status semantics — 401 for auth, 409 for idempotent duplicates, 422 for schema validation — so fleet SRE teams wire alerts without parsing proprietary error strings.
Edge source tags distinguish cellular flush from datacenter replay — critical when diagnosing stale tier reads during connectivity outages. Log correlation IDs propagate from ingest through tier transitions for post-incident review.
Run load tests against sandbox orgs before production keys; replay fixtures from the SDK cover mixed OEM payload shapes without live telematics dependency.
Security and compliance posture
Review org isolation, key rotation, and evidence signing on the security page. API integrations should never embed keys in mobile apps or browser bundles — server-side batch forwarders only.
Data retention policies belong in fleet LOIs; NADIR exports support audit windows without indefinite raw frame storage when partners prefer residual-only ingest.
MSO integrations require separate orgs per fleet customer — persistence enforces boundaries even when shop systems multitenant.
Graduating from shadow to operational tiers
Shadow mode scores every eligible VIN while dispatch rules stay fixed. Graduate only after false CAUTION review, repair partner readiness, and safety board sign-off — document thresholds in pilot closeout exhibits.
Webhook-driven holds should include deep links to evidence bundles so shop forepersons understand detection context. Map CRITICAL to maintenance SLAs defined in maintenance scheduling guide.
Post-repair validation endpoints close the loop — tiers reset after signed shop closure events chain into exports.
FAQ
Do we need ECU access?
No. NADIR monitors fleet residuals in parallel; OEM stacks continue on-vehicle estimation.
Which SDK should we use?
Python for data pipelines; TypeScript for web integrations — parity documented on /developers.
How do idempotency keys work?
Send a stable key per batch; duplicates return 409 without double scoring.
Can MSOs share one org?
Use separate orgs per fleet customer — isolation is enforced at persistence.
Who wrote this guide?
Sri Balaji, Co-Founder and CTO, leads platform and API design at NADIR.
Next steps
Review the NADIR platform, explore the HORIZON pilot walkthrough, and open the Calibration Lab before wiring fleet telemetry. Shadow pilots score every eligible VIN without changing dispatch — the default entry path on the NADIR homepage.
Request a four-week cohort via the footer pilot form or team@nadirai.net with fleet size, telematics partner, and target KPIs for mean time to detect and shop closure rates.