---
title: "Check API key"
method: GET
path: "/check-key"
tags: ["Account"]
---

# Check API key

`GET /check-key`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/check-key`
- Auth: one of:
  - API key in header `X-Acuris-Key`
  - HTTP bearer
  - API key in header `X-API-Key`
  - API key in query parameter `key`
  - none

Returns whether the key is active and the current transaction balance. The
key may be supplied via `X-Acuris-Key`, `Authorization: Bearer`,
`X-API-Key`, or the `key` query parameter — only one method is needed.

## Query parameters

- `key` string

## Response `200`

Key validity and remaining transaction balance for the supplied API key.

- union
  - object
    - `valid` boolean, required
    - `credits` integer, required: Validation + geocode transactions combined. The email and phone pools are separate — see `/account/balances` for all four.
    - `validation_credits` integer: Remaining validation-family trial transactions. Reported as 0 once the trial has expired.
    - `geocode_credits` integer: Remaining geocode-family trial transactions. Reported as 0 once the trial has expired.
    - `key_type` 'trial' | 'subscription': Whether the key is a trial key or a Stripe subscription key.
    - `key_class` string, nullable: `"free_av_geo"` for a verified free-tier account (see **Free tier (verified account)** above) — on these keys `validation_credits` / `geocode_credits` above are a frozen signup-time snapshot, not a live balance; use `free_remaining` instead. `null`/absent for every other key shape (legacy trial, dev key, Stripe subscription).
    - `free_remaining` integer, nullable: Present only when `key_class` is `"free_av_geo"`: today's remaining count against the shared 1,000/day allowance (one number for validate, geocode, reverse and suggest together, not one per product). Resets at UTC midnight. UK PAF usage is never included here — see `uk_trial`.
    - `free_daily_limit` integer, nullable: Present only when `key_class` is `"free_av_geo"`. Always 1000.
    - `uk_trial` object, nullable: UK Royal Mail PAF allowance (`cap`, `used`, `remaining`), capped at **5 per UTC day** for a registered key, resetting at UTC midnight — separate from, and never combined with, `free_remaining`/`credits` above. Present for trial and `free_av_geo` keys alike (any key without a paid UK transaction pack); null for subscribers with a UK pack.
      - `cap` integer
      - `used` integer
      - `remaining` integer
    - `uk_eval` object: Free UK evaluation under the UK PAF Evaluation Terms (trial and free keys).
      - `mode` 'accepted' | 'legacy' | 'required' | 'exempt': `accepted` = terms accepted; `legacy` = key issued before acceptance was required (no acceptance needed until its end date); `required` = must accept before UK lookups work; `exempt` = internal or paid UK key, no evaluation window.
      - `accepted_at` string, nullable: When the UK PAF Evaluation Terms were accepted for this key (`YYYY-MM-DD HH:MM:SS`, UTC), or null.
      - `uk_eval_expires_at` string, nullable: End of this key's free UK evaluation (UTC). Accepted keys: acceptance + 90 days (or the key's own expiry if earlier). Legacy keys: the later of creation + 90 days and the start of enforcement + 14 days. Null when exempt or `required`.
      - `days_remaining` integer, nullable: Whole days left in the UK evaluation (0 once ended).
    - `plan` string: Stripe keys only — the subscribed plan identifier.
    - `shared_primary_pool` boolean: Stripe keys only — `true` when validate and geocode draw from one combined allowance.
    - `trial_expires_at` string, nullable: Trial expiry timestamp (or null if not on a trial).
    - `trial_expired` boolean: True once the trial window has elapsed; the trial transaction pools then read 0.
  - object
    - `valid` boolean
    - `message` string

## Other responses

- `400`: No key provided
- `401`: Invalid key
- `402`: Stripe subscription canceled or transaction pack expired. Body: `{"valid": false, "message": "..."}`.

---

[API](https://skmtc.dev/acuris-geo/apis/acuris-geo-api.md) · [All operations](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/llms.txt) · [OpenAPI document](https://skmtc.dev/acuris-geo/apis/acuris-geo-api/revisions/8547b31dd96a?raw)