Put live auction lots and featured picks on your own website, with the linked dealer’s all-in prices and a lead form that sends visitor requests to the dealer’s cabinet.
The catalogue costs $100 USD per month, paid from your prepaid account balance. UAH accounts are converted at the stored USD/UAH rate when subscribing; that price is saved for renewals. Requests are not billed individually. Manage the subscription and visitor pricing settings in the dashboard’s Catalogue tab.
https://api.notedcar.com/partner/v1
Quick start
Top up your balance, activate the catalogue subscription in the dashboard and create a key. Link a dealer account to show delivered prices and accept leads. Use a secret key on your server, or create a publishable key with your website’s allowed origins for browser requests.
Fetch lots, display their photos and prices, then submit a visitor’s contact details to /leads. Cache catalogue responses per key for one minute. For a sale price, use prices.buy_now.total or a pinned pick price; the current bid total is only an estimate at today’s bid.
# Server-side: list lots
curl "https://api.notedcar.com/partner/v1/lots?currency=usd&lang=en&per_page=12" \
-H "Authorization: Bearer $NOTEDCAR_KEY"
# Browser: submit a lead using a publishable key issued for this origin
curl -X POST "https://api.notedcar.com/partner/v1/leads" \
-H "Authorization: Bearer $NOTEDCAR_PUBLISHABLE_KEY" \
-H "Origin: https://autoimport.ua" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: lead-88213" \
-d '{"lot_id":"lot_48291023","contact":{"name":"Olena","phone":"+380671234567"}}'
Authentication
Send Authorization: Bearer <key> on every request. Keys are created in your dashboard and shown once. Secret keys (nc_live_… or nc_test_…) belong on your server; they can manage subscriptions, picks and billing, and may be restricted to source IP ranges.
Publishable keys (nc_pub_…) can be embedded in your website. They may only read the catalogue and submit leads. Requests must come from an allowed website origin (401 origin_not_allowed otherwise). Billing and subscription management require a secret key.
Publishable keys receive no lot numbers, VINs or auction links unless you enable those fields in the dashboard. Visitor prices follow the account’s price visibility setting: total_only, bid_repair_total or full.
JSON in, JSON out (Content-Type: application/json). Timestamps are ISO 8601 in UTC. Money is in integer minor units of your account currency: kopiyky for UAH (the default), cents for USD; field names use _cents for both.
Catalogue prices are decimal strings in the stated currency (USD or UAH). Auction bid amounts are in USD. lang accepts en, uk or ru and adds translated labels while filter values keep their canonical names. Lot ids use lot_…; lead ids use lead_….
Errors
Errors share one envelope with a stable machine-readable code; details names the field or state when there is one.
{ "error": { "code": "subscription_inactive", "message": "Catalogue subscription is not active." } }
HTTP
code
Meaning
400
invalid_request
Malformed body, invalid filters or contact fields, or an Idempotency-Key reused with a different body
401
unauthorized
Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist
402
insufficient_balance
Balance plus credit limit cannot cover the subscription
404
not_found
Unknown id
401
origin_not_allowed
Publishable key used from a website origin not on its list
403
forbidden_key_kind
Publishable key on an endpoint that needs a secret key
403
subscription_inactive
Catalogue endpoint without an entitled catalogue subscription
403
dealer_not_linked
Prices, destinations or leads on an account with no linked dealer
422
price_unavailable
POST /lots/{id}/estimate cannot price the lot; details.reason says why
429
rate_limited
Catalogue windows, lead submission or top-up creation; see Retry-After
503
provider_unavailable
Upstream data source or payment provider temporarily unavailable; retry later
Rate limits
The catalogue product has anti-scraping windows instead of metering: 300 requests per minute, 5 000 per hour and 30 000 per day per account, counted separately for your secret keys and your publishable keys so visitors can never use up your server's quota (your values are in GET /account → limits.lots and can be raised on request), plus 60 per minute and 600 per hour per visitor IP for publishable keys and 5 leads per minute per IP. 304 Not Modified answers are not counted; catalogue responses carry the same three headers for the window closest to exhaustion.
Top-up creation is limited to 10 per minute per account. A 429 response includes Retry-After in seconds. Cache per API key and send If-None-Match with the previous ETag to reuse unchanged catalogue responses.
Idempotency
Send an Idempotency-Key header with POST /leads to make retries safe. The same key and body replay the original response for 24 hours; a different body with the same key returns 400 invalid_request. Keys are scoped to the API key.
Account
GET/account
Your account, balance, price list and limits
dealer, catalogue, subscriptions.lots and limits.lots describe your website integration. Publishable keys receive only name, dealer, catalogue, limits, key and subscriptions.lots.status; balance and billing fields require a secret key.
The example below shows a publishable-key response. Secret-key responses also include your account balance, pricing, top-up methods and webhook settings.
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
Catalogue
POST/subscriptions/lots
Activate the catalogue subscription
The catalogue costs $100 USD per month, paid from your balance (UAH accounts are converted at the stored USD/UAH rate when subscribing; the subscription saves that price for renewals): the first month is charged now and the catalogue endpoints start answering. Each following month is charged on the renewal date; if the balance cannot cover it you have three days of grace (past_due), then the endpoints answer 403 subscription_inactive until you top up. Leads are always accepted.
DELETE /subscriptions/lots cancels at the end of the paid period; a POST on a cancelled-but-running subscription clears the cancellation without a charge. Secret keys only. The same controls are on the dashboard’s Catalogue tab.
200Already active (a pending cancellation is cleared)
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
402Balance cannot cover the month (insufficient_balance)
403Publishable key (forbidden_key_kind)
GET/lots
Live lots, filtered and paginated, with your prices
Filters: site[], makes[], models[] (canonical names from /filters/makes and /filters/models), year_from, year_to, odometer_min/odometer_max (miles), buy_now_min/buy_now_max (USD), body_type[], damage_primary[], color[], lot_type[], fuel, transmission, drive, status, state, location, auction_date_from/auction_date_to, search. Your dashboard base_filters are always applied underneath; a request can narrow but never widen them.
sort is auction_date (default), price_current, price_buy_now, year, odometer or added; order is asc or desc. page/per_page (max 50; page × per_page ≤ 10 000). destination is an id from /destinations, currency is usd or uah, lang (en/uk/ru) adds translated labels, and include= without prices skips pricing.
prices is present only on an account linked to a dealer and is priced with that dealer’s fees, routes, customs and markup. current_bid.total is what the car would cost if won at today’s bid, which before the sale is usually a few hundred dollars and not a price to print: use buy_now.total, a pinned pick price, or POST /lots/{id}/estimate with a realistic bid. breakdown is null under total_only; it lists bid and repair under bid_repair_total and every component under full. prices is null with a price_unavailable_reason (not_priceable_type, no_route, missing_battery_capacity) when the car cannot be priced.
Publishable keys receive no lot_number, vin or auction_url unless the account opted in (expose_lot_numbers adds the lot number and auction link, expose_vin the VIN); secret keys always receive them plus seller, salvage_id and price_reserve. Responses carry ETag and Cache-Control: private, max-age=60 (the answer depends on the key, so keep caches per key); render server-side with a one-minute cache and a busy site stays far under the limits.
429A catalogue window is exhausted (rate_limited); see Retry-After
GET/lots/{id}
One lot
The same shape as a list item, with every photo and the 360° view links. Any lot your base filters allow can be read, including one whose auction has run (listing_statussold). 404 not_found for a lot outside your base filters or one that has been withdrawn, unless it is one of your picks; GET /lots leaves withdrawn lots out.
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
403subscription_inactive or dealer_not_linked
404Unknown lot
422Cannot be priced (price_unavailable; details.reason)
GET/picks
Featured lots, in order
The lots you featured on the dashboard or with POST /picks. Each item carries the pick’s own fields and the full lot object. A pick whose lot was withdrawn or sold stays in the list with listing_statusdelisted, sold or gone so your page can hide or label it. pinned_price is your own asking price; it is also surfaced as prices.pinned on the lot.
Manage picks with a secret key: POST /picks (lot_id, position, headline, pinned_price: { amount, currency }; 201, or 200 when already featured), PATCH /picks/{id} (any subset; pinned_price: null clears it), DELETE /picks/{id} (204).
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
403subscription_inactive or dealer_not_linked
GET/filters/options
Filter vocabularies
GET /filters/makes and GET /filters/models?make=BMW return canonical names ({ "data": [ { "name": "BMW" } ] }). GET /filters/options returns the raw values every other filter accepts: sites, body_types, fuels, transmissions, drives, damages, colors, document_types, statuses, lot_types, states; with lang each value becomes { value, label }.
GET /dictionary?lang=uk returns translation maps keyed by field (damage, status, body_type, fuel, transmission, drive, document_type, color, lot_type, seller_type), raw value → label, so a site renders Ukrainian or Russian with one lookup. Cache it for a day.
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
403subscription_inactive
POST/leads
A visitor’s request
Allowed with a publishable key, so a static page can post it. Requires a linked dealer: the lead lands in that dealer’s cabinet under Requests with a “website” badge and triggers the same notifications as the NotedCar order form. contact.name and contact.phone are required by default (the dashboard can change the required set; it is reported in GET /account → catalogue.lead_fields). quoted_total stores the price the visitor saw. website is a honeypot and must be empty.
Send Idempotency-Key to make retries safe (lead keys are kept per API key, apart from history-report keys). Without expose_lot_numbers, a publishable key's answer carries no lot.lot_number. Send X-NotedCar-Dry-Run: true (or use an nc_test_… key) to validate without saving: the answer is the would-be lead with dry_run: true. Secret keys can GET /leads (cursor-paginated; filters status, lot_id, created_after, created_before) and PATCH /leads/{id} with { "status": "contacted" }. Leads are limited to 5 per minute per visitor IP and are not counted against the catalogue windows.
400Missing required fields (details.missing), honeypot filled, bad page_url
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
403dealer_not_linked
404Unknown lot
429More than 5 leads per minute from one IP
Top-ups
POST/topupsRate-limited: 10 requests per minute per account.
Add funds to your balance
Returns the payment to complete; the balance is credited once the provider confirms, usually within seconds for card and within a minute or two on-chain. A topup.paid webhook is sent when it lands.
For crypto_direct there is no payment_url; crypto_payment holds what to send and where: { network, network_name, currency, amount, address, qr_svg, expires_at, expired }. Send exactly amount (the trailing decimals identify your order) before expires_at, 30 minutes after creation.
Statuses: pending → processing (payment seen, crediting) → paid; or payment_failed (declined, expired or cancelled; nothing credited).
Body
amount_cents*
integer
In your account currency; bounds in GET /account → topups
payment_method
monobank | crypto_direct
Default monobank (card). Only methods listed in GET /account → topups.methods are accepted
payment_network
string
crypto_direct only, one of topups.crypto_networks[].id
payment_currency
string
crypto_direct only, one of that network’s currencies
return_url
https URL
Optional, where the card payment page sends the payer afterwards
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
404not_found
GET/topups
Your top-ups, newest first
Same cursor pagination as /history-reports.
Query parameters
limit
integer
Default 50, max 200
cursor
string
From next_cursor
Responses
200OK
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
POST/topups/{id}/claim
Claim an on-chain payment by transaction hash
For a crypto_direct top-up you paid after it stopped being watched, or when you do not want to wait for the next scan. Answers 200 with state: "paid", or a waiting state (not_found, unconfirmed, unavailable) to poll through.
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
404not_found
422invalid_request with details.state saying why the transaction does not pay for this top-up
Billing
GET/ledger
Balance history, newest first
Same cursor pagination as /history-reports. kind is one of topup, charge, refund, adjustment; charges are negative; each entry names the product it belongs to.
401Missing, invalid, expired or revoked key, suspended account, or IP outside the key’s allowlist (unauthorized).
Testing your integration
nc_test_… secret keys read the real catalogue and calculate real prices. They do not provide fixture lots or a free catalogue subscription.
To test a lead without saving it, use a test key or send X-NotedCar-Dry-Run: true with POST /leads. The response contains the validated lead with dry_run: true. Top-ups and catalogue subscriptions are not sandboxed.
