API reference

One REST API for the platforms that bring us candidates. Create exam credits, read outcomes for a group, verify a serial, and receive signed webhooks.

Base URL: https://siaa-assess.vercel.app/api/v1
Authorisation: Authorization: Bearer siaa_… on every call except the public ones; 120 requests per minute.
OpenAPI 3.1: /api/v1/openapi.json

Endpoints

Exam credits

POST /entitlements: Create an exam credit for one person; send an Idempotency-Key header to repeat a request safely.
GET /entitlements: Read outcomes for a group: pass, fail, sat, not sat or withheld, for the candidates who consented.

Credentials

GET /credentials: Read the credentials of a candidate you linked through a claim link, by your external_ref.
GET /skillspublic: List the skills an Applied AI Badge can certify.

Verify a serial

GET /verify/{serial}public: Verify one serial; 404 when there is no public credential.
POST /verifypublic: Verify up to 100 serials in one call.

Courses

POST /progress: Report course progress for a candidate; idempotent per candidate, course and module, up to 100 events.
GET /prerequisite: Ask whether a candidate completed a course you reported.

Exams you run yourself

GET /sittings/{id}: Read the report for one exam you invited a candidate to. Organisation keys only.
POST /sittings: The first name of the create call under Exam credits. It still answers, and its headers name the one to use instead.

Quick start

curl -X POST https://siaa-assess.vercel.app/api/v1/entitlements \
  -H "Authorization: Bearer siaa_YOUR_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: person-42-L1" \
  -d '{"class":"siaa","level":"L1","candidate_name":"A. Candidate","candidate_email":"you@example.com","external_ref":"person-42","cohort":"2026-autumn","callback_consent":"outcome"}'
# → {"entitlement_id":"…","redeem_url":"https://siaa-assess.vercel.app/claim/…","expires_at":"…"}
curl "https://siaa-assess.vercel.app/api/v1/entitlements?cohort=2026-autumn" -H "Authorization: Bearer siaa_YOUR_KEY"
curl "https://siaa-assess.vercel.app/api/v1/credentials?external_ref=person-42" -H "Authorization: Bearer siaa_YOUR_KEY"
curl https://siaa-assess.vercel.app/api/v1/verify/SIAA-XXXX-XXXX-XXXX

The claim link signs the candidate in with the address you gave and binds your external_ref to their record. Before the exam starts, they choose whether you may learn pass or not yet. Your webhook then receives credential.outcome. An ATS can drive the same 3 steps: create the credit, send the link, receive the outcome.

Signed webhooks

We POST to your URL with X-Timestamp and X-Signature: sha256=HMAC-SHA256(secret, X-Timestamp + '.' + body). 3 attempts with backoff. Events: credential.outcome (partner keys), sitting.graded (organisation keys) and test.ping.

Set the URL and the events under Settings in your console. Send a test event, read the delivery log and replay any delivery from there. Sandbox keys create credits that cannot be redeemed and count nowhere, for integration tests.