Window Sticker API reference

Order original window sticker PDFs by VIN with equipment, options and MSRP. Prepaid billing, automatic refunds and sandbox samples.

Version 1. The shared OpenAPI 3.1 specification covers all products: https://api.notedcar.com/partner/v1/openapi.yaml.

Get an API key

Overview

Order original manufacturer window sticker PDFs by VIN, including factory equipment, options, MSRP and EPA information. The PDF keeps its original language.

Uses your existing secret API key and prepaid balance. Window stickers have separate price tiers and VIN ownership from Carfax. Once a sticker is ready for your account, ordering that VIN again is free. Failed orders are refunded automatically.

A saved sticker URL is reused first; supported manufacturers such as Jeep are checked for a free PDF before a paid data-source request.

https://api.notedcar.com/partner/v1

Authentication

Every request carries your API key as a bearer token. Keys are created in your dashboard and shown once. You may hold several active keys and rotate them without downtime; a key can be restricted to a list of source IP ranges. Keep keys server-side; never embed them in client applications.

Keys come in two modes. nc_live_… keys order real reports and spend balance. nc_test_… keys are sandbox keys: same account, same endpoints, deterministic answers, fixture PDFs, nothing charged and no data source called (see Sandbox below).

Authorization: Bearer nc_live_3kq9Zt7Hc2mVbL8xRwQp4nY6sDfG1aJeUoT5iKzM

Rate limits

Window sticker and history report availability checks share the per-account limit shown in GET /account (default 120 per minute). Orders and polling are not rate-limited. A 429 includes Retry-After.

Idempotency

Send Idempotency-Key with single-order POST requests. The same key and body replay the original response for 24 hours; a changed body returns 400 invalid_request. Window sticker keys are scoped by product and live/test mode. Batch requests do not support this header.

Window stickers

GET/window-stickers/availabilityRate-limited: 120 requests per minute per key.

Free check whether a sticker can be produced for a VIN

Free availability check: a cached sticker, a manufacturer PDF, or a likely result from the data source. Unknown availability is not sold by the single-order endpoint. Returns vin, available, already_ordered and price_cents (null when unavailable).

Query parameters

vin*

string

17-character VIN

Response

{"vin":"1C4RJYB65RC720863","available":true,"already_ordered":false,"price_cents":2000}

Responses

200OK (available: false when the data source has no report)
400invalid_request — malformed VIN
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
429rate_limited
503provider_unavailable

POST/window-stickers

Order a sticker

Accepts vin and optional client_reference. Charges the current window sticker tier. 201 means an owned PDF is ready immediately; 202 means queued. Poll the order or wait for a webhook. 422 report_unavailable and 503 provider_unavailable create no order or charge.

Headers

Idempotency-Key

string ≤ 128

Optional. Same key + same body within 24 h replays the original response.

Body

vin*	string	17-character VIN
client_reference	string ≤ 128	Optional, echoed back and included in webhooks

Request

{"vin":"1C4RJYB65RC720863","client_reference":"order-88213"}

Response

{
  "id": "ws_01J9R5X3M6Q7V8W9Y0Z1A2B3C4",
  "vin": "1HGCM82633A004352",
  "language": null,
  "status": "queued",
  "sandbox": false,
  "price_cents": 4500,
  "client_reference": "order-88213",
  "vehicle": "2003 HONDA ACCORD EX",
  "created_at": "2026-10-08T10:15:02Z",
  "ready_at": null,
  "data_as_of": null,
  "download_url": null,
  "download_url_expires_at": null,
  "failure_code": null
}

Responses

201Ready immediately
202Accepted and queued
400invalid_request
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
402insufficient_balance
422report_unavailable — nothing charged
503provider_unavailable

POST/window-stickers/batch

Order up to 100 stickers in one call

Accepts 1–100 objects with vin and optional client_reference. Each item succeeds or fails independently. Duplicate VINs are rejected. Prechecks are skipped; unavailable stickers fail and refund in the job. No batch idempotency header.

Body

items*

array (1–100)

Objects with vin (required) and optional client_reference

Request

{"items":[{"vin":"1C4RJYB65RC720863"},{"vin":"YV4A22PK5G1040979"}]}

Response

{
  "data": [
    { "index": 0, "status": 202, "order": { "id": "ws_…", "status": "queued" } },
    { "index": 1, "status": 402, "error": { "code": "insufficient_balance", "message": "…" } }
  ]
}

Responses

200One result per item
400invalid_request — items missing, empty or over 100
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).

GET/window-stickers/{id}

Order status and download link

States: queued, processing, ready, failed. Ready orders include a signed PDF link valid for one hour; poll again for a fresh link. Original PDF language is preserved; language and data_as_of are null.

Failure codes: sticker_not_found, provider_error, download_error, daily_limit_reached. All failed live charges are refunded.

Response

{
  "id": "ws_01J9R5X3M6Q7V8W9Y0Z1A2B3C4",
  "vin": "1HGCM82633A004352",
  "language": null,
  "status": "ready",
  "sandbox": false,
  "price_cents": 4500,
  "client_reference": "order-88213",
  "vehicle": "2003 HONDA ACCORD EX",
  "created_at": "2026-10-08T10:15:02Z",
  "ready_at": "2026-10-08T10:15:41Z",
  "data_as_of": null,
  "download_url": "https://…",
  "download_url_expires_at": "2026-10-08T11:15:41Z",
  "failure_code": null
}

Responses

200OK
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
404not_found

GET/window-stickers

List your orders, newest first

Lists only your window sticker orders in the current key mode, newest first. Same filters and cursor pagination as Carfax orders.

Query parameters

vin	string	Filter by VIN
status	string	`queued`, `processing`, `ready` or `failed`
client_reference	string	Exact match
created_after	ISO 8601
created_before	ISO 8601
limit	integer	Default 50, max 200
cursor	string	From `next_cursor`

Response

{
  "data": [ { "id": "ws_…", "vin": "…", "status": "ready" } ],
  "next_cursor": "eyJpZCI6…"
}

Responses

200OK
400invalid_request — bad timestamp or cursor
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).

Webhooks

Configure a webhook in the dashboard. Events are window_sticker.ready and window_sticker.failed, with the order object in data. Signatures and retries use the same HMAC scheme as Carfax. Ledger entries use product: "window_stickers" and window_sticker_id. Account pricing and usage include a window_stickers block.

Sandbox

Test keys call no provider and charge nothing. VINs ending in 0000 are unavailable, 1111 succeed after a delay and 9999 fail after a delay; others are ready immediately. Ready PDFs are fixed samples, not documents for the requested VIN.

VINs beginning with 1C4 receive the free Jeep sample (2024 Grand Cherokee 4xe); others receive the VINReport sample (2016 Volvo XC90). Top-ups remain live.