Developer documentation · get a key · product page

AerKYC API — Quick Start for Developers

Base URL: https://aerkyc-api.vercel.app Version: 1.0 · 18 July 2026 Audience: Aeredium engineers integrating AerKYC

1. Get a key

Every /v1 endpoint needs an API key in the Authorization header. There are three ways to get one:

Sandbox / test key (start here). Use this shared key to try everything immediately. It is trial-tier and rate-limited — never use it for production traffic:

aer_test_vJwZNZ60rnfaQQJ_xCCAZ-9UyFegXIT7
Your own trial key (self-serve). Open https://aerkyc-api.vercel.app/developers, click “Sign in with wallet”, sign the message — you get a personal 14-day key on the spot.
Live production key. Issued by Albert. These are metered and billed; keep them server-side only.

Send the key on every call:

Authorization: Bearer <your-key>

Rule 1: keys live on servers, never in a mobile app, browser, or committed to git. The applicant-facing flow (section 5) exists precisely so client apps never hold a key.

2. Health & what’s switched on

No key needed:

curl https://aerkyc-api.vercel.app/health
curl https://aerkyc-api.vercel.app/v1/connectors

/health reports liveness and persistence mode. /v1/connectors shows which data sources are currently enabled.

3. Verify a company (KYB)

curl -X POST https://aerkyc-api.vercel.app/v1/verifications/company \
  -H "Authorization: Bearer <your-key>" \
  -H "content-type: application/json" \
  -d '{"company":{"name":"BHP Group Limited","jurisdiction":"AU"}}'

Optional fields inside company: registration_number (ABN/company number) and lei. Add a reference at the top level to tag the check with your own ID.

You get back a verdict, a score (0–100), reasonCodes, the resolved company identifiers, a signed evidence block, and completedInMs.

4. Verify a person (KYC) — server-to-server

curl -X POST https://aerkyc-api.vercel.app/v1/verifications/person \
  -H "Authorization: Bearer <your-key>" \
  -H "content-type: application/json" \
  -d '{
    "person": {
      "given_name": "Jane",
      "family_name": "Citizen",
      "date_of_birth": "1990-05-14",
      "address": { "country": "AU" }
    },
    "consent": { "given": true, "timestamp": "2026-07-18T21:00:00+10:00" },
    "wallet": "0xAbC...123"
  }'

consent.given must be true and is mandatory. wallet is optional (binds the result to a wallet address). The response always includes "data_retention": "attributes_purged" — the person’s details are checked and erased; only the signed verdict persists.

Screening only (no full verification, cheapest call):

curl -X POST https://aerkyc-api.vercel.app/v1/screenings/person \
  -H "Authorization: Bearer <your-key>" \
  -H "content-type: application/json" \
  -d '{"name":"Jane Citizen","date_of_birth":"1990-05-14","nationality":"AU"}'

5. The hosted flow (let the user enter their own details)

Best practice for consumer onboarding — your app never touches the person’s data. Two steps:

Your backend starts a session (this is the AAP path; the AAP key is used here):

curl -X POST https://aerkyc-api.vercel.app/v1/aap/kyc/begin \
  -H "Authorization: Bearer <aap-key>" \
  -H "content-type: application/json" \
  -d '{"subject_ref":"your-opaque-user-id","jurisdiction":"AU"}'

You get back a kyc_record_id and a flow_url.

Open the flow_url for the user (in-app webview or browser). They fill in the branded page, consent, and submit. The engine verifies and purges. Your backend then polls:

curl https://aerkyc-api.vercel.app/v1/aap/kyc/<kyc_record_id>/result \
  -H "Authorization: Bearer <aap-key>"

The result is reference-only — status, risk, reason codes, evidence hash — never the person’s identity data. subject_ref must be an opaque ID, never a name or email.

6. Wallet status (safe to expose)

Check whether a wallet is verified — returns status only, never identity data, so it’s safe for dApp backends:

curl https://aerkyc-api.vercel.app/v1/wallet/0xAbC...123/status \
  -H "Authorization: Bearer <your-key>"

7. Reading the result

Verdicts:

verified — passed.
verified_with_notices — passed, with minor flags (e.g. a lapsed LEI). Usually acceptable.
review — needs a human. A sanctions or PEP candidate matched; do not auto-approve or auto-reject.
failed — a hard check failed (e.g. registry says deregistered).
no_match — the entity/person could not be confidently resolved.

Reason codes explain the verdict in machine-readable form — e.g. REGISTRY_ACTIVE, LEI_ACTIVE, NO_SANCTIONS_HITS, SANCTIONS_HIT, PEP_HIT, ENTITY_DEREGISTERED. Gate your own logic on these, not on free text.

Score is 0–100. Set your own thresholds per use case.

8. Verifying our signatures (no key needed)

Every verdict carries a JWS signature. Anyone can verify it offline against our public keys — you never have to trust or re-call us:

curl https://aerkyc-api.vercel.app/.well-known/jwks.json

The signature is ES256, key id aerkyc-1, issuer aerkyc.aeredium.com, covering the verification id, verdict, score and evidence hash. Verify with any standard JOSE library.

9. Errors you’ll see

400 — bad request body (check required fields; the response says what’s wrong).
401 — missing or invalid API key.
404 — id not found.
409 — a hosted-flow session was already submitted (one submission per session).
429 — rate limit hit (public/demo endpoints are 10 req/min per IP; sandbox key is limited too).
503 — a data source isn’t configured yet; the response names what’s missing.

10. Rules of the road

Keys server-side only; one key per service so usage is metered and revocable independently.
Never log a person’s attributes, and keep subject_ref opaque — no names or emails in references or logs.
Treat review as “send to a human,” never as pass or fail.
The signed evidence bundle is delivered to the regulated record-keeper; AerKYC keeps only its hash. If you need to prove a result later, keep the signature.
Sandbox key for trying, live key for production — don’t mix them.

Questions: Albert. Full reference: the AERKYC repo, docs/ (architecture and the AERWallet integration guide).