Developer Documentation

Programmatic Access lets your application request and receive vehicle data — historical, last-known, and real-time — directly from our APIs through the platform. You register an integration once, receive credentials, and then call the data-request APIs to create requests, track their status, and retrieve delivered data.

Three things are true of every integration, and they shape everything else in this guide:

• Access is read-only. The business integration realm is a zero-trust, read-only environment. You can request data about a vehicle; you cannot send commands to a vehicle (no door unlock, no engine start). Those capabilities live in a separate fleet realm and are not exposed here.
• The vehicle owner is always in control. Data only flows after the owner has explicitly consented to the specific data you asked for, for the specific purpose you stated. You initiate; the owner approves. There is no path that bypasses owner consent.
• The platform meters and bills automatically. Pricing, payment, and invoicing are enforced by the platform before any backend service runs. Your backend never handles pricing logic — you register a payment method and the platform does the rest.

If you have integrated with OAuth providers or other consent-gated data APIs before, the overall shape will feel familiar. The one concept that is easy to under-estimate — and the one that causes the most integration bugs — is consent as a first-class, owner-controlled lifecycle that is independent of your access tokens. The Consent section is the most important in this guide; read it before you write code.

There are three actors:

Every request follows the same arc, regardless of integration model or data family:

The request does not return data synchronously at creation time. Creating a request returns a requestId and a status. You then either poll the status or subscribe to a webhook to learn when consent is granted and data is ready. Only when the request reaches APPROVED with consent GRANTED does data become retrievable.

Consent is owner-granted, scope-specific, time-bounded, revocable, and independent of your tokens. Internalize these five properties and most lifecycle questions answer themselves.

You initiate; the owner approves

For security and data-protection compliance, the act of granting consent always happens in the owner's own secure portal session — never through your credentials. A business partner can initiate a consent request via API, but cannot grant it. How the owner is brought into the loop differs by integration model:

• M2M (server-to-server): When you create a request, the platform emails the owner a secure deep-link. They follow it, authenticate, review exactly what you asked for (data, purpose, time range), and approve or deny.
• App (Authorization Code + PKCE):The owner is redirected to the Nissan IdP login + Consent Screen inline during your app's authorization flow, approves there, and is redirected back to your app.

Either way, the owner sees a plain-language description of your request — for example, "Allow [App Name] to access your driving-style data to provide a personalized insurance quote."

Scope-specific and additive-only

Consent is granted at the package level (see Data families). A grant covers exactly the packages and purpose you requested — nothing more. You cannot silently widen scope. If you later need data attributes that were not in the original grant, you must create a new request for the additional scope, which the owner approves separately. This enforces data minimization.

Time-bounded

Every grant carries a duration. Historical requests are bounded by a date range; subscriptions run for an agreed term. When the term ends, consent reaches a terminal "expired" state and data stops automatically.

Revocable at any time

The owner can revoke an active consent from their portal at any moment. Revocation is immediate: real-time streams associated with that grant are terminated and no further data flows. Your integration must treat revocation as a normal, expected event — not an error — and stop relying on that data.

Independent of your access tokens

This is the property most likely to bite you. Your OAuth/M2M token lifecycle and the consent lifecycle are two separate things.

• A valid, unexpired access token does not mean you are entitled to data. Entitlement is gated by stored consent, evaluated fresh on every data access.
• Conversely, refreshing or re-minting a token does not re-grant or extend consent.

So: a real-time read can return 403/no-data even with a perfectly valid token, because the owner revoked consent or the term expired. Always check the request/consent status, not just your token, before assuming data is available.

Consent request expiry

If the owner never acts on a pending request, the request expires after a configurable window (commonly ~7 days, with reminders) and the secure link becomes invalid. The opportunity is closed and you must initiate a fresh request. You are notified of expiry via webhook/polling like any other status change.

Before any data is read, every request passes through a centralized compliance engine — three sequential gates. If any gate fails, the request is terminated immediately. You don't call these gates; they run for you. Knowing they exist explains why a request can be rejected even when your call is well-formed.

Gate 3 is why a historical request can succeed but return less data than the full date range you asked for: only the portion of the window during which the consenting owner actually owned the vehicle is eligible.

Every service package belongs to one of three families. The family determines the delivery mechanism, the request endpoint, and the billing model. List the packages available to your account before creating a request (see the service-package catalog); use the returned package id values in your request body.

Notes that matter in practice:

• Data availability is vehicle-dependent. For retrieving recorded values, a given vehicle supports either the Historical (time-series over a date range) option or the Last Known Value option — not necessarily both. Some vehicle models expose only the last-known-value service. Always rely on the service-package catalog and the package type to see what is actually available for your account and the vehicles you query, rather than assuming a vehicle supports historical.
• Real-time delivery is event-driven, not a raw firehose. Subscriptions surface meaningful events — e.g., journey completed, charge-state changed, safety fault — rather than continuous raw pings. This protects your receiving infrastructure. Pull reads give you the latest known state on demand.
• A resource can legitimately return no dataif the vehicle doesn't support it. For example, the charging resource returns 404 for non-EV (ICE) vehicles.
• Very high-volume continuous telemetry is out of scope here. Webhook-based delivery is designed for self-serve SME-to-mid scale. If your run-rate or frequency needs grow past the threshold for managed streaming, that is a managed high-throughput streaming tier conversation — contact your account team rather than working around webhook limits.

Billing is enforced by the platform, not your backend. The model depends entirely on the data family / request type — not on whether the call came from an M2M backend or an app.

The prerequisite: a valid payment method

Your API credentials remain suspended until your business account has a complete billing profile and a valid primary payment method (a credit or debit card). Until then, data-request calls are blocked. Add a payment method in account settings to activate.

Pricing tier

Pricing is rendered dynamically by account type:

• SME — margin-free rate.
• Large Enterprise — commercial rate.

You don't pass a price; the platform computes it from your account type and the requested package.

Workflow A — One-off historical & last-known (strict prepaid)

A pre-authorization hold is placed for the exact price when the request is created. Payment is captured only at the moment consent is granted; if the owner never consents, the hold is released and nothing is charged.

Workflow B — Recurring subscriptions (periodic & real-time, postpaid aggregated)

Because consented VINs can be added or revoked organically throughout the month, individual VINs are not charged per transaction. Instead, on the 1st of each month, an aggregated billing job sums all active, consented VINs for your account over the prior month and raises a single consolidated charge.

Invoices & retention

Invoices are generated at capture (Workflow A) or at the monthly aggregation (Workflow B) and are available in the portal. Financial records are retained for tax-compliance purposes independently of account deletion.

The platform prices the request, not the vehicle. How your app derives the requested period therefore decides how often you are charged — see Billing for the charging mechanics.

Worked example

A quotation app sends periodStartDate = today - 30 days and periodEndDate = today. A user who submits on Monday and again on Tuesday creates two requests over two different windows — two pre-authorization holds, and two captures once each is consented.

Pattern 1 — check existing coverage before you create

Before every POST .../historical/data-requests, list what already exists for that VIN:

curl -G "{API_BASE}/cms/m2m/accounts/{account_id}/historical/data-requests" \
  -H "Authorization: Bearer <access_token>" \
  --data-urlencode "vin=VF1AAAAA000000001" \
  --data-urlencode "requestType=ONE_OFF" \
  --data-urlencode "requestStatus=PENDING" \
  --data-urlencode "requestStatus=APPROVED" \
  --data-urlencode "requestStatus=COMPLETED" \
  --data-urlencode "pageSize=100"

The list endpoint filters on vin, requestType, requestStatus and consentStatus — there is no date-range filter. Each item returns periodStartDate, periodEndDate, packages, reference and createdAt, so do the window comparison in your own code:

1. Fetch the VIN's ONE_OFF requests in the statuses that can still cost you money — PENDING, APPROVED, ACTIVE, COMPLETED.
2. Compare the window you are about to ask for against each request's periodStartDate–periodEndDate and package set.
3. Already covered and consented? Re-read the existing deliveries instead of requesting the same data again.
4. Still PENDING for that window? Wait for the owner to act rather than stacking a second hold on your payment method.
5. Nothing covers it? Then create the request.

Pattern 2 — snap dynamic windows to a stable grid

Rather than anchoring the range to the wall clock, quantize it: a whole calendar month, or a window that only moves once a week. Repeat submissions inside the same slot then resolve to the identical period, which is what makes the Pattern 1 coverage check actually hit. Show the resolved window in your UI so the user sees the period they are paying for.

Pattern 3 — guardrails in your own application

• Cap creation yourself. A hard ceiling per VIN and per end-user — for example one one-off request per VIN per calendar month — is the only limit fully under your control. Enforce it in your backend, before the API call.
• Stamp a correlation key in reference (up to 255 characters) — for example a digest of VIN + package set + period. It is returned on the list response, so detecting a repeat is a string comparison rather than a field-by-field diff.
• Serve data you already hold. A delivered extract stays usable for its retention window; re-requesting the same window buys nothing but another charge.
• Make submission deliberate. Confirm window, packages and cost in the UI behind an explicit user action. Never create a request as a side effect of a page load, a refresh, or a client-side retry.
• Reconcile continuously.Subscribe to the consent & billing webhooks and alert on requests-per-day run-rate anomalies, rather than discovering them on the invoice.

Pattern 4 — use PERIODIC when the need is recurring

If the use case genuinely needs a rolling window on an ongoing basis, a PERIODIC request with MONTHLY frequency is billed through the aggregated monthly charge (Workflow B) on one consent round, instead of a fresh prepaid request per submission. That is far more predictable per VIN than repeated ONE_OFF calls — see Data families.

You pick the authorization model when you create the integration, and it cannot be changed afterwards. If you need both, create two integrations.

Rule of thumb: if a human owner is present in your UX and you want them to authenticate and consent in the moment, use App (PKCE). If you're running unattended backend jobs against VINs your organization is permitted to act for, use M2M and rely on email-link consent capture. Both share the same package catalog, the same data-request lifecycle, and the same billing model.

Make sure the following are in place for your business account. Data requests are blocked until every gate below passes.

• An active business account (not suspended), and your organization is not on a sanctions/gatekeeper blocklist (Gate 1).
• A complete billing profile with a valid primary payment method (a credit or debit card). Until this exists, your API credentials are suspended.
• Accepted platform terms and Data Terms & Conditions.

Development vs. production: a development account is sandboxed and vehicle-count-limited for PoC and pre-prod validation; a primary account runs live, contracted services. Build and validate against development first.

From the Programmatic Access tab, choose Create Integration and complete the form:

• Application name (3–50 characters).
• Authorization model — M2M or Authorization Code. Immutable after creation.
• Redirect URLs — required for Authorization Code. These are the only URLs the authorize step will redirect back to (exact match).
• Purpose of the integration (shown to owners in the consent prompt).
• Service packages you intend to request.
• Accept the Data Terms & Conditions.

Submit to register. You can later update most fields, but the authorization model stays fixed.

Your credentials

After creation, credentials are shown once in a popup. Store them securely before closing it (you can also download a PDF summary).

• M2M: a client_id and a client_secret (the secret is shown only once).
• Authorization Code: a client_id only (no secret — security comes from PKCE).

A service package defines the data a request can access, and which family/billing it falls under. List what's available to your account before creating a request:

M2M

GET {API_BASE}/cms/m2m/accounts/{account_id}/service-packages?dataType=HISTORICAL|REAL_TIME

App (PKCE) — same shape, OAuth path + dual-token headers:

GET {API_BASE}/cms/oauth/accounts/{account_id}/service-packages?dataType=HISTORICAL|REAL_TIME

Each package returns at least an id, name, description, and type. Use the package id values in the packages array when you create a data request. The catalog is the source of truth for what a given vehicle/account supports — including whether historical time-series or only last-known-value reads are available (see Data families).

Backend service, no interactive login. Consent is captured via an emailed secure link to the owner.

1. Your backend → Platform API: POST /cms/m2m/token (client credentials)
2. Platform API → Your backend: access_token
3. Your backend → Platform API: POST data-request (VIN, package, owner email)
4. Platform API → Vehicle owner: Email secure consent link
5. Platform API → Your backend: requestId, status = PENDING
6. Vehicle owner → Platform API: Approve in secure portal
7. Platform API → Your backend: Webhook CONSENT_GRANTED (or poll status)
8. Your backend → Platform API: GET data (deliveries / resource)
9. Platform API → Your backend: Pre-signed download URL or JSON

Step 1 — Get an access token

Exchange your account ID and client credentials for a bearer token:

curl -X POST "{API_BASE}/cms/m2m/token" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_ID",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET"
  }'

The response contains an access_token and its expires_in lifetime. Send it on every subsequent call:

Authorization: Bearer <access_token>

Step 2 — Create a data request

Use the endpoint that matches the package family:

A request identifies a vehicle (17-character vin), the vehicle user's email (used to notify the owner for consent), and one or more package id values. Historical requests also take requestType (ONE_OFF or PERIODIC), a date range, and — for periodic — a frequency. The exact field names and validation rules are in the API reference.

What happens behind the scenes: the platform runs synchronous validations (valid VIN, resolvable user, active ownership pairing, temporal limits — see Compliance constraints), creates a PENDING record, sets up the billing hold (Workflow A) or validates the payment method (Workflow B), and emails the owner a secure approval link. The call returns a requestId and status — no data yet.

A one-off historical request is held at creation and charged once consent is granted, so each distinct period you ask for is a separate charge. Read Cost control before deriving the period from a dynamic expression.

Step 3 — Monitor the request

Poll the list endpoints (filter by vin, requestStatus, consentStatus, with paging), or subscribe to a webhook to be pushed status changes:

Wait for requestStatus = APPROVED and consentStatus = GRANTED. See Data-request lifecycle & statuses.

Step 4 — Retrieve data

Historical — list deliveries, then fetch a time-limited download URL:

Real-time — once approved, read a telematics resource directly:

See the real-time telematics catalog for valid {resource} values.

Use this when an individual owner authorizes your app. PKCE means no client secret.

1. Your app: Generate PKCE verifier + challenge
2. Your app → Platform API: Redirect owner to /authorize (challenge)
3. Platform API → Nissan IdP: Redirect for login
4. Vehicle owner → Nissan IdP: Authenticate
5. Nissan IdP → Vehicle owner: Consent prompt
6. Vehicle owner → Nissan IdP: Approve
7. Platform API → Your app: Redirect to callback (auth code)
8. Your app → Platform API: POST /cms/oauth/token (code + verifier)
9. Platform API → Your app: access_token + id_token + refresh_token
10. Your app → Platform API: GET data (Authorization + X-Id-Token)
11. Platform API → Your app: Data

Step 1 — Generate a PKCE verifier and challenge (per authorization attempt)

// Keep the verifier private; send only the challenge to /authorize.
const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
const digest = await crypto.subtle.digest(
  "SHA-256",
  new TextEncoder().encode(verifier)
);
const codeChallenge = base64url(new Uint8Array(digest));

Step 2 — Redirect the owner to the authorize endpoint

{API_BASE}/cms/oauth/authorize
  ?account_id=YOUR_ACCOUNT_ID
  &client_id=YOUR_CLIENT_ID
  &redirectUri=https://your-app.example.com/callback
  &codeChallenge=BASE64URL_SHA256_OF_VERIFIER
  &codeChallengeMethod=S256

The owner logs in via the Nissan IdP, sees the plain-language consent prompt for the scopes you requested, approves, and is redirected back to your redirectUri with an auth code.

Step 3 — Exchange the code for tokens (on your callback, using the original verifier)

curl -X POST "{API_BASE}/cms/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "AUTH_CODE_FROM_CALLBACK",
    "redirect_uri": "https://your-app.example.com/callback",
    "client_id": "YOUR_CLIENT_ID",
    "code_verifier": "ORIGINAL_VERIFIER"
  }'

You receive an access_token, an id_token, and a refresh_token.

Step 4 — Call owner-scoped APIs with dual tokens

Every /cms/oauth/accounts/... call requires both headers:

Authorization: Bearer <access_token>
X-Id-Token: <id_token>

The owner-scoped endpoints mirror the M2M ones:

Step 5 — Refresh tokens before they expire

The refresh token rotates on each use — store the new one each time:

curl -X POST "{API_BASE}/cms/oauth/token/refresh" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "refreshToken": "YOUR_REFRESH_TOKEN"
  }'

A request moves through several states as the owner consents and data is delivered. Poll the list endpoints or use webhooks to track it. These are the authoritative enums returned by the API:

The consent lifecycle, in brief:

How to read the statuses together:

• PENDING / consentStatus = PENDING — created, owner notified, awaiting action. No data.
• APPROVED + GRANTED — the only state in which data is retrievable. Real-time reads and historical deliveries are available here.
• DECLINED / consentStatus = DENIED — owner rejected. Terminal; initiate a new request if still needed.
• EXPIRED (request) / consentStatus = EXPIRED — either the request lapsed before the owner acted, or the consent term ended. Terminal; create a fresh request.
• REVOKED — owner revoked an active grant; data stops immediately. Terminal for that grant.
• SUPERSEDED (consent) — a newer consent grant has replaced this one (e.g., re-scoped request).
• COMPLETED — a one-off request whose delivery has been fulfilled.
• INVALID / CANCELLED — failed validation (bad VIN, no ownership link, etc.) or was cancelled.

Historical (file delivery)

Historical results are prepared asynchronously and delivered as zipped CSVs via a time-limited pre-signed download URL (session/IP- restricted). The flow:

1. Request reaches APPROVED + GRANTED and (Workflow A) payment is captured.
2. List deliveries: GET .../historical/data-requests/{requestId}/data-deliveries.
3. Fetch the download URL: GET .../data-deliveries/{dataDeliveryId}/download.
4. Download promptly — the URL expires.

If you created the request via API and subscribed to webhooks, you'll receive a delivery-ready event instead of needing to poll.

Last-known value

Last-known packages return the most recent known value(s) synchronously as JSON — no date range, no async file. Availability is vehicle-dependent (see Data families); expect a single response per call.

Real-time (pull)

Once APPROVED + GRANTED, read the latest known state of a resource on demand:

GET {API_BASE}/cms/{m2m|oauth}/accounts/{account_id}/realtime/vehicles/{vin}/{resource}

Real-time (push)

Subscribe a webhook to receive events on state change instead of polling. Real-time push is event-driven (e.g., journey completed, charge-state changed, safety fault).

Real-time resources are read per vehicle via .../realtime/vehicles/{vin}/{resource}. Available {resource} values:

Instead of polling, subscribe a webhook and the platform pushes events to your endpoint. Two payload families are delivered: real-time telemetry push and consent & billing lifecycle events. Both arrive as HTTPS POSTs signed with HMAC-SHA256 — register once, verify the signature, then route on the payload.

Register your endpoint

You can register from the portal UI or the webhook API. In the portal:

1. Log in to the Portal.
2. Open the Data Catalog tab in the top navigation.
3. Switch to the Programmatic Access tab.
4. In the Advanced Programmatic Access card, click Configure Webhook.

In the dialog you provide:

• A publicly reachable HTTPS callback URL.
• An HMAC key (up to 32 characters) used to sign and verify payloads.

Subscriptions are managed against your business account:

Deliveries originate from the platform's (MyNissanData) webhook delivery service over HTTPS. If your infrastructure requires source IP allow-listing, request the current egress range for your environment from your account team.

Registration handshake (ownership challenge)

When you register a callback URL, the platform verifies you own it before it will send events:

1. The platform sends a challenge to your URL.
2. Your endpoint must echo the challenge back in the response.
3. On a match, the subscription is saved and set active.

Type 1 — Real-time telemetry push (telemetry-push)

Delivered when a subscribed vehicle emits a real-time event. Every delivery uses the same envelope; the event data is carried in payload:

{
  "eventId":   "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
  "eventType": "telemetry-push",
  "eventTime": "2026-06-01T12:34:56.000Z",
  "vin":       "SJNJ12TDXU2117834",
  "payload":   { "soc": 80 }
}

Signature verification (X-MND-Sig)

Each delivery carries an HMAC-SHA256 signature in the X-MND-Sig header (lowercase hex, 64 characters). Compute it over the eventTime, a literal dot, and the raw request body:

signed string = <eventTime> + "." + <raw request body>
X-MND-Sig     = HMAC_SHA256(signed string, your_hmac_key)   // lowercase hex

• eventTime — the top-level eventTime value from the body, used verbatim.
• raw body — the exact bytes you received; do not re-serialize the JSON before hashing.
• Compare case-sensitively and in constant time.

Test vector — verify your implementation against this:

signing key : whsec_sample_key_do_not_use_in_prod
eventTime   : 2026-06-01T12:34:56.000Z
raw body    : {"eventId":"3f2504e0-4f89-41d3-9a0c-0305e82c3301","eventType":"telemetry-push","eventTime":"2026-06-01T12:34:56.000Z","vin":"SJNJ12TDXU2117834","payload":{"soc":80}}
signed str  : 2026-06-01T12:34:56.000Z.{"eventId":"3f2504e0-4f89-41d3-9a0c-0305e82c3301","eventType":"telemetry-push","eventTime":"2026-06-01T12:34:56.000Z","vin":"SJNJ12TDXU2117834","payload":{"soc":80}}

X-MND-Sig   = 9ba0f7246a45239eeccf4bf3a5e7833aed475e3b56a4865c65478c2d956b6d2a

Type 2 — Consent & billing events

Consent-lifecycle and download-payment notifications use a different envelope: match on the top-level event and read the data object. Validate the X-MND-Sig signature the same way before processing.

CONSENT_GRANTED — consent granted (example shows a partial grant, one package denied):

{
  "event": "CONSENT_GRANTED",
  "data": {
    "requestId": "3f1c8e2a-9b4d-4f7a-8c21-0d5e6f7a8b90",
    "appId": "9a2b7c3d-1e4f-4a5b-9c8d-2e3f4a5b6c7d",
    "accountId": "acct-10023",
    "consentStatus": "GRANTED",
    "requestStatus": "APPROVED",
    "requestType": "REAL_TIME",
    "timestamp": 1752566400000,
    "vin": "WVWZZZ1KZAW000001",
    "packages": [
      { "id": "PKG_LOCATION", "name": "Location Data", "status": "GRANTED" },
      { "id": "PKG_TELEMATICS", "name": "Telematics", "status": "DENIED" }
    ]
  }
}

CONSENT_DENIED — vehicle user declines the request:

{
  "event": "CONSENT_DENIED",
  "data": {
    "requestId": "7b2d1f04-3c6e-4a19-b0f2-5a8c9d1e2f30",
    "appId": "9a2b7c3d-1e4f-4a5b-9c8d-2e3f4a5b6c7d",
    "accountId": "acct-10023",
    "consentStatus": "DENIED",
    "requestStatus": "DECLINED",
    "requestType": "HISTORICAL",
    "timestamp": 1752570000000,
    "vin": "WVWZZZ1KZAW000001",
    "packages": [
      { "id": "PKG_TRIPS", "name": "Trip History", "status": "DENIED" }
    ]
  }
}

CONSENT_REVOKED — a previously granted consent is revoked or cancelled (example reflects app termination: request → CANCELLED, consent + packages → REVOKED):

{
  "event": "CONSENT_REVOKED",
  "data": {
    "requestId": "c4a9e6b1-8d20-4f3c-9a7e-1b2c3d4e5f60",
    "appId": "9a2b7c3d-1e4f-4a5b-9c8d-2e3f4a5b6c7d",
    "accountId": "acct-10023",
    "consentStatus": "REVOKED",
    "requestStatus": "CANCELLED",
    "requestType": "REAL_TIME",
    "timestamp": 1752573600000,
    "vin": "WVWZZZ1KZAW000001",
    "packages": [
      { "id": "PKG_LOCATION", "name": "Location Data", "status": "REVOKED" }
    ]
  }
}

CONSENT_EXPIRED — consent auto-expired (no user action within the consent window):

{
  "event": "CONSENT_EXPIRED",
  "data": {
    "requestId": "e1f2a3b4-5c6d-4e7f-8a9b-0c1d2e3f4a5b",
    "appId": "9a2b7c3d-1e4f-4a5b-9c8d-2e3f4a5b6c7d",
    "accountId": "acct-10023",
    "consentStatus": "EXPIRED",
    "requestStatus": "EXPIRED",
    "requestType": "HISTORICAL",
    "timestamp": 1752577200000,
    "vin": "WVWZZZ1KZAW000001",
    "packages": [
      { "id": "PKG_TRIPS", "name": "Trip History", "status": "EXPIRED" }
    ]
  }
}

PAYMENT_FAILED — a download-time invoice payment could not be resolved (the API call is rejected with HTTP 402):

{
  "event": "PAYMENT_FAILED",
  "data": {
    "requestId": "a8b7c6d5-e4f3-4a2b-9c8d-7e6f5a4b3c2d",
    "accountId": "acct-10023",
    "appId": "9a2b7c3d-1e4f-4a5b-9c8d-2e3f4a5b6c7d",
    "invoiceId": "inv-2026-000789",
    "status": "FAILED",
    "message": "Payment could not be completed",
    "requestType": "ONE_OFF",
    "vin": "WVWZZZ1KZAW000001"
  }
}

Real-time connected-vehicle data reaches you in one of two ways: you pull the last-known value of a resource whenever you ask, or you receive a signed webhook push the instant an event happens. Your subscribed package decides which data groups you are entitled to — see Webhooks for the delivery mechanics.

What triggers a delivery

Package × trigger matrix

● delivered by webhook  ·  ○ available on pull  ·  — not applicable

The four real-time packages

• Telemetry Snapshot (pkg.rt.telemetry_snapshot) — current position, mileage and energy/fuel level for a vehicle. On-demand pull only — no webhook.Unlocks Geolocation, Odometer and Fuel & Energy.
• Usage-Based Insurance (pkg.rt.ubi_insurance) — a completed-journey summary with driving-behaviour metrics, for pay-how-you-drive products. Pushes on JOURNEY.COMPLETED. Unlocks Driver Behaviour, Tire Pressure, Geolocation and Odometer.
• Smart Charging (pkg.rt.smart_charging) — EV state-of-charge and charging-session events, for energy and charging platforms. Pushes on CHARGE.STATE.CHANGED, plus on-demand pull of energy state. Unlocks Fuel & Energy and Geolocation.
• Remote Diagnostics (pkg.rt.remote_diagnostics) — safety and health faults, for repair and roadside providers. Pushes on SYSTEM.SAFETY.FAULT, plus on-demand pull of safety alerts. Unlocks System Safety, ADAS, Engine Health and EV Health.

Every real-time field, grouped by data group: the signal received from the vehicle, the field delivered in the message, its type and unit, an official description, and the complete value-to-meaning mapping. Read it alongside the package × trigger matrix to know which fields a given package actually delivers.

Pull API endpoints

GET {base}/vehicles/{vin}/{section}
Authorization: Bearer <access_token>

The pull API returns the last-known value for a section. The platform serves these sections (public path names are assigned by the API gateway):

Webhook events

Delivery is a signed POST to your registered endpoint.

Message shapes

Pull response:

{
  "vin": "...",
  "serviceName": "geolocation",
  "data": { "geolocation": { ... } },
  "metaData": {
    "responseStatus": "SUCCESS",
    "message": "..."
  }
}

Webhook body:

{
  "eventId": "...",
  "eventType": "CHARGE.STATE.CHANGED",
  "eventTime": "2026-06-01T12:34:56.000Z",
  "vin": "...",
  "payload": {
    "chargeSession": { ... },
    "location": { ... }
  }
}

How to read this dictionary

Signal received is the raw vehicle signal; Field delivered is the JSON key you actually receive, and it is the authoritative name — it is not always a mechanical camelCase of the signal (StatusDistanceTotalizerComputed arrives as mileage, VCMEVSOCStatusDisplay as stateOfCharge). Numeric fields pass through unchanged. Coded fields carry both the integer code and its enum label — the Value column lists each code with the exact label delivered (e.g. 1 = ECO). A suppressedcode is the vehicle's "no data" marker: that field is dropped rather than sent.

Push vs pull — which groups go where

A webhook is not a full vehicle snapshot; each event pushes only the fields listed below. The pull API serves every group on demand.

Geolocation

Pull: section location  ·  Webhook: included in every event for context

Odometer

Pull: section cockpit  ·  Webhook: JOURNEY.COMPLETED

Driver Behaviour

Pull: section behavior  ·  Webhook: JOURNEY.COMPLETED

CCS availability: the journey trip-summary metrics are on both CCS1 & CCS2 (except averageTripSpeed — CCS2 / EVO only). The live per-signal fields in the first table are CCS2 / EVO only, except speedDisplayedValue (both).

Fuel & Energy

Pull: section charging  ·  Webhook: CHARGE.STATE.CHANGED

ADAS (Driver Assistance)

Pull only — section adas. Not delivered on any webhook: the SYSTEM.SAFETY.FAULT payload carries only the alert-code fields, not the ADAS subdocs. CCS2 / EVO only

Engine Health

Pull only — sections healthstatus · cockpit. The descriptive health fields (healthAlert.*, statusMilLampRequest, gearbox, air/coolant temp) are not on the webhook; only their alert-code equivalents (OIL_PRESSURE_WARNING, MIL_ON…) ride SYSTEM.SAFETY.FAULT.

Tire Pressure

Pull: section tirepressure  ·  Webhook: JOURNEY.COMPLETED  ·  per-wheel state CCS2 / EVO only

EV Health

Pull: section healthstatus  ·  Webhook: SYSTEM.SAFETY.FAULT (both fields are alert codes, so they do ride the webhook)

System Safety & Faults

Pull: section healthstatus  ·  Webhook: SYSTEM.SAFETY.FAULT — this is the only group delivered in full on the fault webhook (these are the alert-code fields + location)

Access, Security & Cabin

Pull only — sections security · occupancy · hvac. CCS2 / EVO only (doors, locks, windows, sunroof, occupancy, HVAC are not populated on CCS1)

Lighting & Visibility

Pull only — section visibility. most fields CCS2 / EVO only (brake lamp, low beam, flashing indicator, warning lights)

These are data-protection constraints enforced by the platform. Designing for them up front avoids confusing rejections and partial results.

Temporal limits on historical requests

• Earliest requestable date: 12 September 2025 (the effective date). You cannot request data older than this.
• Maximum 90 days per historical request. Split longer ranges into multiple requests.
• Lookback limited to ~3 years. Older history is not available.

Ownership / entitlement (Gate 3)

• Data is only eligible for the portion of your requested window during which the consenting owner actually owned the vehicle. A valid request can therefore return a shorter window than asked.
• Entitlement resolution differs by vehicle generation: for older generations an active ownership link suffices; newer generations additionally verify the active driver against the linked owner. The net effect for you: don't assume every request yields the full range — handle partial results.

Data minimization (Gate 2)

• You receive exactly the packages/scopes the owner approved. Need more? Initiate a new request.

Governance (Gate 1)

• Sanctioned or gatekeeper-designated entities are blocked at login and at request time.

Retention & deletion

• Delivered files and decisions are retained as audit records under the platform's retention policy. Financial records persist for tax compliance even after account deletion.

• The API Gateway applies rate-limiting policies. Build in retry-with-backoff and treat 429 as transient.
• Validate against a development account (sandboxed, vehicle-count-limited) before going to production.
• Real-time/webhook delivery suits self-serve SME-to-mid volumes. If sustained run-rate or frequency grows beyond the platform's managed-streaming threshold, that's a managed high-throughput streaming tier conversation — contact your account team rather than working around webhook limits.
• Token hygiene: store the rotating refresh token after every refresh (App); never ship the client secret to a client device (M2M).

The reference below is generated from the live OpenAPI specification. Use it for exact request/response schemas and to try endpoints interactively.

In the portal, the interactive Swagger UI is embedded below. The OpenAPI document is served (per environment) from: