---
title: "Self-serve evaluation key (zero-friction onboarding)"
method: POST
path: "/dev-key"
tags: ["Account"]
---

# Self-serve evaluation key (zero-friction onboarding)

`POST /dev-key`

## Request

- Base URL: `https://api.acuris-geo.com`
- URL: `https://api.acuris-geo.com/dev-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

**Recommended way to start.** Mints a low-cap, short-lived evaluation
key in one step — no password, no email round-trip, no free-domain
block. The key is returned directly in the response body.

The key seeds ~100 transactions in **each** pool (validation, geocode —
separate pools) and expires after **7 days**. These
are trial-pool credits: the pool decrements **1 per call** regardless of
endpoint. (Under a paid Stripe plan the same endpoints instead cost
weighted transactions — e.g. validate=1, geocode=1, reverse=1.)

Rate-limited to 1 issuance per email and 1 per IP in any 24-hour window
(and 60 requests/hour per IP overall). For more headroom, use the full
`/register` flow (28-day trial). Per-product daily free limits apply to
anonymous use — check remaining via `/validate-credits` and
`/geocode-credits`; anonymous access is also rate-limited per IP.

## Request body

- object
  - `email` string, required: A valid email address to associate with the key. Free providers (Gmail etc.) are accepted.
  - `accept_terms` boolean: `true` = you agree to the Acuris Geo [Terms of Service](https://api.acuris-geo.com/legal/terms) and the [UK PAF Evaluation Terms](https://api.acuris-geo.com/legal/uk-evaluation-terms). Starts the key's 90-day UK evaluation. When terms acceptance is enforced, a request without it returns 400 `terms_acceptance_required`; send it on every request.
  - `country` string, nullable: Optional ISO country hint (e.g. `gbr`). Drives the returned `info_url` and, for `gbr`, adds a `paf_note` about UK (Royal Mail PAF) evaluation limits.

## Response `200`

Evaluation key issued. Send it as `X-Acuris-Key: <key>` (or `Authorization: Bearer`, `X-API-Key`, or `?key=`) on subsequent calls.

- DevKeyResponse
  - `api_key` string, required: The evaluation key. Send it as `X-Acuris-Key: <key>` (or `Authorization: Bearer` / `X-API-Key` / `?key=`) on validation/geocoding calls.
  - `validation_credits` integer, required: Address-validation pool seeded on the key.
  - `geocode_credits` integer, required: Geocode pool seeded on the key.
  - `phone_credits` integer, required: Offline phone-validation pool seeded on the key.
  - `expires_at` string, required: Expiry timestamp (UTC), 7 days from issuance.
  - `tier` string, required
  - `info_url` string, required: Pricing / info page (UK-specific for a `gbr` country hint).
  - `next_steps` string, required: Short onboarding note pointing to `/register` for more headroom.
  - `paf_note` string, nullable: Present only when the request `country` hint is `gbr` — notes that UK addresses (Royal Mail PAF) are evaluation-only under a dev key.
  - `uk_evaluation_expires_at` string, nullable: Present only when the request sent `"accept_terms": true` — end of the key's free UK evaluation (UTC).

## Other responses

- `400`: Missing or malformed email (`error: bad_email`), or, when terms acceptance is enforced, `accept_terms` missing or not `true` (`error: terms_acceptance_required`, with `terms_url` and `uk_evaluation_terms_url`).
- `429`: Rate limited — a dev key was already issued to this email (`error: rate_limited_email`) or from this IP (`error: rate_limited_ip`) in the last 24 hours, or the hourly request limit was exceeded.
- `500`: Could not issue dev key (`error: internal`).

---

[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)