Account Balance API & Email Alerts

Read your current balance without consuming credits or retrieving historical usage.

GET /api/v1/account/balance

Use the VINquery Portal host with a valid API Consumer JWT issued by identity.vinquery.com/connect/token. Reuse your existing service audience. The response contains only the balance pools for that audience:

Audience	Balances returned
vinquery:api:vindecode	Lite, Basic, Standard, Extended VIN credits
vinquery:api:vinfix	VINfix VIN credits
vinquery:api:vinocr, vinquery:api:vinbarcode, vinquery:api:lpr	Shared image recognition credits
vinquery:api:decisioq	DecisioQ operation credits

The API requires an active customer API Consumer, an approved account owner, and enabled JWT account access. Portal management and internal consumer tokens cannot use this endpoint. The account comes from the validated token and its current consumer association. Do not supply account IDs or other query parameters.

Example request

curl --fail-with-body https://www.vinquery.com/api/v1/account/balance \
  --header "Authorization: Bearer $VINQUERY_JWT"

Example response

For a DecisioQ consumer:

{
  "service": "account",
  "version": "1.0",
  "status": "SUCCESS",
  "observedAtUtc": "2026-09-11T18:25:00+00:00",
  "balances": [{
    "pool": "decisioq",
    "unit": "operations",
    "allocated": 100000,
    "used": 17500,
    "remaining": 82500,
    "unlimitedAccessActive": null,
    "unlimitedAccessDaysRemaining": null,
    "unlimitedAccessExpiresAt": null,
    "latestPaidPurchase": {
      "orderId": 123456,
      "credits": 100000,
      "paidAt": "2026-09-01T10:00:00",
      "isReconstructed": false
    },
    "percentRemaining": 82.5
  }]
}

VINdecode pools use VINs; recognition uses images. allocated is the total deposited quantity. DecisioQ stores available and consumed operations, so its allocation is their sum. These are existing account totals, not a monthly allowance or a new billing plan. Missing account pools are omitted; a present pool with no credits returns its actual zero values. No balances are cached.

percentRemaining is total remaining credits divided by the latest completed paid volume purchase's credits, multiplied by 100. Free trials, unpaid orders, and time-limited purchases are excluded. Carryover can make the percentage exceed 100%. With no qualifying paid purchase, both latestPaidPurchase and percentRemaining are null, and percentage alerts cannot fire. Historical purchase quantities reconstructed from the package definition have isReconstructed: true; future completed purchases retain a quantity snapshot.

observedAtUtc is when the read completed. Purchase dates and unlimitedAccessExpiresAt use account time without an assumed UTC offset. VINdecode also reports whether time-limited access is active and the remaining calendar days; volume credits remain separate.

Errors use HTTP problem details: 400 for query parameters, 401 for a missing, invalid, or expired token, 403 for unauthorized account access, and 503 when unavailable. Responses must not be cached.

Configure email alerts

Open Account Balance & Notifications from your dashboard. Select a pool, enter thresholds and recipient addresses, then save. The enable checkbox is selected by default for pools without saved preferences. Alerts become active after you save enabled preferences with at least one threshold and recipient. Previously saved choices are preserved.

• Choose up to 10 distinct whole-number thresholds between 0% and 100%. Suggested thresholds are 25%, 10%, and 5%; 0% is optional.
• Configure up to 5 distinct email recipients per pool, one address per line. Recipients do not have to match your login email.
• A threshold fires once when the balance moves from above it to at or below it. Further consumption below that threshold does not repeat the alert.
• A single drop from 30% to 8% marks both 25% and 10% crossed, and sends one consolidated 10% email per recipient.
• A replenishment from 8% to 12% rearms 10%, while 25% stays triggered. Later depletion below 10% can notify again. Reaching exactly 10% does not rearm it.
• Enabling a low-balance alert while already below its percentage threshold establishes a baseline and sends no immediate email. A new paid purchase starts a new baseline; changing the reference alone does not send email.
• Emails are processed asynchronously. Disabling alerts, removing recipients, or deselecting thresholds cancels affected emails still waiting to send. An email already being sent may complete.

Time-limited access expiry alerts

VINdecode Lite, Basic, Standard, and Extended each have a separate expiry-alert checkbox and reminder days. The defaults are 10, 5, and 1 days before access expires. The checkbox starts selected until you save a choice; enter recipients and save to activate reminders. Expiry and percentage alerts can be enabled independently and share the pool's recipient list.

• Choose up to 10 distinct whole-number reminder days from 0 to 365. Include 0 only if you want a notice when access expires.
• The portal checks end dates on its configured email-worker interval, even when you make no API calls or have no volume credits. With an hourly worker, reminders may arrive about an hour after entering a reminder window, plus any queue delay.
• Each selected day sends once per access end date. A reminder becomes due when that many 24-hour days or less remain. Renewing to a new end date starts a new reminder series; queued reminders for the old date are cancelled.
• If several reminders are already due when you enable alerts or the worker resumes, only the most urgent one is sent. Access that expired before you enabled alerts does not generate historical notices. Without 0 selected, no new email is sent after expiry.
• Saving the same settings or disabling and re-enabling alerts does not repeat reminders already recorded for that end date. Messages already being sent may complete.

SMTP failures are recorded and do not affect your API operations. Contact VINquery support if an expected email does not arrive. Detailed consumption history remains available in My Usage.