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 data if 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

Granting consent triggers the invoice and hold automatically: the platform issues an invoice for the exact packages the owner approved and places a hold for that amount in the same step. The hold is reserved, not captured — no charge occurs while the data is being prepared, and if the owner never consents, no hold is placed and nothing is charged.

Payment is only captured when the requester initiates the download. If capture succeeds, the download link is released; if it fails, the download is blocked and the requester is notified that payment is required.

Workflow B1 — Recurring subscriptions (Periodic)

Workflow B2 — Recurring subscriptions (Realtime)

Both subscription workflows share the same consent and billing model; they differ in delivery. Periodic subscriptions deliver on a schedule, while real-time subscriptions stream continuously — you either pull the current value from the API or receive a webhook push as signals arrive. Real-time delivery is not gated on the monthly invoice; data flows for the whole billing period and the charge is deducted automatically on the 1st.

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 generates a single consolidated invoice.

Invoices & retention

Invoices are generated at capture (Workflow A) or at the monthly aggregation (Workflows B1 and B2) 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 (Workflows B1 and B2) 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 + access-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, validates the payment method, 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 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 + refresh_token
10. Your app → Platform API: GET data (Authorization)
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 and a refresh_token.

Step 4 — Call owner-scoped APIs with Access Token

Every /cms/oauth/accounts/... call carries the owner's access token:

Authorization: Bearer <access_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 sections are read per vehicle via .../realtime/vehicles/{vin}/{section}. Each section answers with its own serviceName token, which is what the response envelope carries — not the URL segment. Available {section} 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.

Events

A field the vehicle did not report is omitted rather than sent as null. Coded fields carry both the integer value and its label.

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

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": "CHARGE.STATE.CHANGED",
  "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":"CHARGE.STATE.CHANGED","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":"CHARGE.STATE.CHANGED","eventTime":"2026-06-01T12:34:56.000Z","vin":"SJNJ12TDXU2117834","payload":{"soc":80}}

X-MND-Sig   = 1d116cccde8627fcd09e6a8820d248c478230354ec0064da5e2ec3060334fd49

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.

Choose a delivery mode by how you want the data; choose a package by what data you need. A subscription can combine packages.

Two delivery modes

Which package do I need?

Pull API — packages that let you call sections on demand:

Webhooks — packages that deliver an event to your endpoint:

Make your first pull call

1. Get an access token — OAuth2 client-credentials, using your M2M account credentials.
2. Call the section you want for a VIN: GET /cms/m2m/accounts/{account_id}/realtime/vehicles/{vin}/location with Authorization: Bearer <token>.
3. Read the fields from data — flat for a single-object section, or keyed by sub-object otherwise. Check metaData.responseStatus: SUCCESS means the vehicle has reported that section.

What triggers a delivery

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 /location, /cockpit and /charging pull access.
• 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 only — no on-demand pull access.
• 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 /cockpit and /charging.
• 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 /behavior, /tirepressure, /occupancy, /security, /hvac, /visibility, /healthstatus and /adas.

Every real-time field, grouped by pull section or webhook event: the field delivered in the message, its type and unit, an official description, the complete value-to-meaning mapping, and the vehicle models that deliver it. Read it alongside the package × trigger matrix to know which fields a given package actually delivers.

Part 1 — Pull API

On-demand access to the last-known value of a vehicle resource. Call an endpoint for a section and receive its current value.

How the pull API works

The pull API is on-demand: each call returns the last-known value the platform holds for one section of a vehicle. There is no streaming and no polling contract — you read a section whenever you need its current state.

Request

GET {API_BASE}/cms/m2m/accounts/{account_id}/realtime/vehicles/{vin}/{section}
Authorization: Bearer <access_token>

OAuth2 (client-credentials). {account_id} is your M2M account, {vin} the target vehicle, {section} one of the sections below.

Response envelope

{
  "vin": "SJNJ12TD1U2232824",
  "serviceName": "VEHICLE_LOCATION",
  "data": { ... section fields ... },
  "metaData": { "responseStatus": "SUCCESS", "message": "VEHICLE_LOCATION data available." }
}

serviceName is a fixed token per section — not the URL segment; see the matrix below. data holds the section's fields: a single-object section (/location, /tirepressure) returns them flat; every other section returns data keyed by sub-object — for example data.odometer, data.speed. Coded fields are delivered as { "label": …, "value": … } objects.

A section the vehicle has not reported returns metaData.responseStatus = FAILED with HTTP 200 (not an HTTP error) and the message No <serviceName> data available. Fields — and whole sub-objects — the vehicle did not report are omitted from data rather than sent as null.

Example responses

/location — single object, data flat:

{
  "vin": "SJNJ12TD1U2232824",
  "serviceName": "VEHICLE_LOCATION",
  "data": {
    "locationLatitude": 48.825026944444,
    "locationLongitude": 2.0747516666667,
    "locationHeading": 220,
    "latitudeAtStart": 48.799281388889,
    "latitudeAtEnd": 48.840693888889,
    "longitudeAtStart": 2.0439263888889,
    "longitudeAtEnd": 2.2295127777778,
    "lastKnownLocationAltitude": 210,
    "locationSource": { "label": "A_IVI", "value": 1 },
    "locationValidity": { "label": "VALID", "value": 0 },
    "locationSourceAtStart": 1,
    "locationSourceAtEnd": 1,
    "lastUpdated": "2026-09-10T06:32:30.313Z"
  },
  "metaData": { "responseStatus": "SUCCESS", "message": "VEHICLE_LOCATION data available." }
}

/cockpit — multiple objects, data keyed by sub-object:

{
  "vin": "SJNJ12TD1U2232824",
  "serviceName": "COCKPIT",
  "data": {
    "odometer": {
      "mileage": { "value": 6607.47, "unit": "km" },
      "mileageLife": { "value": 6150.8, "unit": "km" },
      "mileageCoveredInTrip": { "value": 97.4, "unit": "km" },
      "totalDistanceStartTrip": { "value": 6494.41, "unit": "km" },
      "totalDistanceEndTrip": { "value": 6478.07, "unit": "km" },
      "lastUpdated": "2026-09-10T06:32:30.313Z"
    },
    "fuelLevel": {
      "fuelGaugeDisplayValue": 17,
      "fuelLowLevel": 0,
      "ecoAverageDistanceForFuelEconomy": { "value": 5, "unit": "km/L" },
      "lastUpdated": "..."
    },
    "dte": {
      "distanceToEmpty": { "value": 157, "unit": "km" },
      "bRangeFrequencyInTrip": 1,
      "lastUpdated": "..."
    },
    "speed": {
      "speedDisplayedValue": { "value": 117.4, "unit": "km/h" },
      "averageTripSpeed": { "value": 69.73, "unit": "km/h" },
      "statusSpeedUnit": { "label": "KM/H", "value": 0 },
      "averageSpeedWheelFrontLeft": { "value": 106.14, "unit": "km/h" },
      "lastUpdated": "..."
    }
  },
  "metaData": { "responseStatus": "SUCCESS", "message": "COCKPIT data available." }
}

Sections & package entitlement

Each section is its own endpoint. Your subscribed package decides which sections you may call.

Package × endpoint matrix

Package → pull sections it grants

Section field reference

Every field delivered in each pull section — the JSON key you receive, its type and unit, an official description, the value-to-meaning mapping, and the vehicle models that deliver it. The field lists below are the complete set returned by the live API, grouped exactly as the response nests them.

How to read this reference

Field delivered is the JSON key you actually receive, and it is the authoritative name — it is not always a mechanical camelCase of the underlying vehicle signal (StatusDistanceTotalizerComputed arrives as mileage, VCMEVSOCStatusDisplay as stateOfCharge). Numeric fields pass through unchanged. Coded fields carry both the integer code and its enum label.

/location — Geolocation

serviceName: VEHICLE_LOCATION. Single-object section — data holds these fields flat.

/cockpit — Odometer, Fuel & Speed

serviceName: COCKPIT. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

/charging — EV Charge Status

serviceName: VEHICLE_CHARGE_STATUS. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

Additional in-scope fields — delivered when the vehicle reports them (conditional; absent from the sample snapshot but part of the section).

/behavior — Driver Performance

serviceName: DRIVER_PERFORMANCE_DATA. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

Additional in-scope fields — delivered when the vehicle reports them (conditional; absent from the sample snapshot but part of the section).

/tirepressure — Tire Pressure

serviceName: VEHICLE_TIRE_PRESSURE. Single-object section — data holds these fields flat.

/occupancy — Presence & Seat-belts

serviceName: VEHICLE_PRESENCE_STATUS. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

Additional in-scope fields — delivered when the vehicle reports them (conditional; absent from the sample snapshot but part of the section).

/security — Doors, Locks & Windows

serviceName: VEHICLE_SECURITY. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

Additional in-scope fields — delivered when the vehicle reports them (conditional; absent from the sample snapshot but part of the section).

/hvac — HVAC & Cabin Climate

serviceName: VEHICLE_HVAC_STATUS. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

Additional in-scope fields — delivered when the vehicle reports them (conditional; absent from the sample snapshot but part of the section).

/visibility — Lighting & Wipers

serviceName: VEHICLE_LIGHTING_STATUS. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

/healthstatus — Health, EV Health & System Safety

serviceName: VEHICLE_HEALTH_STATUS. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

The alerts map is keyed by alert code; each value is { active, severity, label, rawValue }. Use the active flag — do not derive it from rawValue, as the rule differs by code. Alert codes actually delivered:

Additional in-scope fields — delivered when the vehicle reports them (conditional; absent from the sample snapshot but part of the section).

/adas — Driver Assistance

serviceName: VEHICLE_ADAS. data is keyed by sub-object; each sub-object also carries its own lastUpdated.

Field values come from the platform signal registry; descriptions and value meanings come from the Nissan Data Dictionary. A field the vehicle did not report is omitted, never sent as null.

Part 2 — Webhooks

Event-driven delivery: the fields sent in each real-time webhook event. See Webhooks for the envelope, registration and signature mechanics.

A field the vehicle did not report is omitted rather than sent as null. Coded fields carry both the integer value and its label.

JOURNEY.COMPLETED

Sent at ignition-off. The payload below is the complete set of fields delivered, grouped by their JSON key. Number fields that carry a unit are delivered as { "value": …, "unit": "…" }.

{
  "eventType": "JOURNEY.COMPLETED",
  "eventTime": "2026-08-17T16:52:05.190Z",
  "vin": "...",
  "payload": {
    "vin": "...",
    "journeyId": "B795...3709",
    "status": "COMPLETED",
    "closeReason": "IGN_OFF",
    "interimCount": 1,
    "accountId": "...",
    "location": {
      "latitudeAtStart": 52.404,  "longitudeAtStart": 4.8045,
      "latitudeAtEnd":   52.5257, "longitudeAtEnd":   6.0619,
      "locationHeading": 146
    },
    "odometer": {
      "mileageCoveredInTrip":   { "value": 126.6,   "unit": "km" },
      "totalDistanceStartTrip": { "value": 41615.6, "unit": "km" },
      "totalDistanceEndTrip":   { "value": 41742.1, "unit": "km" }
    },
    "speed": {
      "averageTripSpeed": { "value": 87.9, "unit": "km/h" }
    },
    "header": { "stopTripTimestamp": "2026-08-17T15:48:09Z" }
  }
}

CHARGE.STATE.CHANGED

Sent when the vehicle's charge status changes — state-of-charge or battery capacity. Delivers the chargeStatus object (state of charge + battery capacity) + current location.

Charging-session state — chargeStatus, evChargePlugConnected and hvBatteryChargeType — is not carried on this event. Read it on demand from /charging.

SYSTEM.SAFETY.FAULT

Sent the instant a new safety or health fault is detected. Delivers the alerts object (a map of active alert codes) + current location. A fault is delivered as an alert code — for example OIL_PRESSURE_WARNING.

The alerts object is a map keyed by alert code; each value has these fields:

Alongside the alert codes, the alerts object carries its own lastUpdated, and the event carries the current location object:

The alerts map lists every monitored alert code with its current state — active: false means the alert is not raised (OK), active: true means it is currently raised.

{
  "eventId": "a04fa8f6-...",
  "eventType": "SYSTEM.SAFETY.FAULT",
  "eventTime": "2026-09-07T05:31:04.933Z",
  "vin": "*************5788",
  "payload": {
    "alerts": {
      "MIL_ON":               { "active": false, "rawValue": "0", "label": "OK",      "severity": "WARN" },
      "ABS_FAIL":             { "active": false, "rawValue": "0", "label": "OK",      "severity": "HIGH" },
      "WHEEL_RR":             { "active": false, "rawValue": "0", "label": "OK",      "severity": "WARN" },
      "OIL_PRESSURE_SWITCH":  { "active": false, "rawValue": "0", "label": "OK",      "severity": "HIGH" },
      "OIL_PRESSURE_WARNING": { "active": true,  "rawValue": "1", "label": "WARNING", "severity": "HIGH" },
      "lastUpdated": "2026-09-07T05:31:04.933Z"
    },
    "location": {
      "locationLatitude": 52.5216, "locationLongitude": 6.0607, "locationHeading": 0
    }
  }
}

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: