Training Verification API: overview

Training Verification checks a training certificate against what Healthier Business holds. You send a certificate (a PDF or an image) with the candidate's name and email address and the agency named on it. Hub reads it and matches the candidate (automated), or passes it to Healthier Business staff (manual), and tells you the outcome by webhook and through this API.

The API does exactly what the Hub form does, with the same rules, prices, file types and size limit. Everything lives under /api/v2/training-verification.

Who it is for

Agencies and employers that use other Hub services: automated verification is free for you. Manual verification is charged.

Verification-only accounts (they use Training Verification and nothing else): every verification is charged, from verification credits first.

Who pays for what has the full table.

How a verification works, end to end

You submit. POST /api/v2/training-verification/verifications with the candidate, the agency and the certificate. The answer is 202 Accepted with the verification in status pending. Request a verification lists every field.

You are charged, once, from credits and balances only. There is no card payment through the API. When nothing covers the charge the answer is 402 insufficient_credits and nothing is stored. See Who pays for what.

The check runs afterwards. An automated request is read and matched by Hub within minutes. A manual request is passed to Healthier Business staff and stays processing until they decide.

You learn the outcome. The status becomes verified, not_found, rejected or failed. Webhooks tell you at once (Webhooks); GET /verifications/{id} shows the result, including the courses found (Statuses and results).

You download what you need. The original certificate, and a PDF report once the verification is verified.

You can cancel while it is still pending: it becomes rejected with the reason code cancelled_by_client and a charge is refunded.

Automated or manual

	Automated (`auto`)	Manual (`manual`)
Who checks	Hub reads the certificate and matches the candidate	Healthier Business staff
How long	Minutes	Until staff decide
Status while it runs	`pending`, then `processing`	`pending`, then `processing` until staff decide
Price	Free on a regular account, charged on a verification-only account	Charged on every account

Authentication and scopes

Exchange your API key for a token with POST /api/v2/auth/token, then send Authorization: Bearer <access_token>. Sandbox keys start with hbk_test_, live keys with hbk_. See API keys and tokens.

Scope	Allows
`training-verification:read`	Every `GET`: account, prices, balances, ledger, verifications, events, certificate and report
`training-verification:write`	`POST verifications` and `POST verifications/{id}/cancel`. It also grants read

training-verification:* covers the portal and * covers everything. A client without a Training Verification account gets 403 portal_unavailable on every call.

The eleven endpoints

Call	Operation id	Scope
`GET /profile`	`training-verification.profile.show`	read
`GET /pricing`	`training-verification.pricing.show`	read
`GET /credits`	`training-verification.credits.show`	read
`GET /credits/transactions`	`training-verification.credits.transactions`	read
`POST /verifications`	`training-verification.verifications.create`	write
`GET /verifications`	`training-verification.verifications.list`	read
`GET /verifications/{id}`	`training-verification.verifications.show`	read
`GET /verifications/{id}/events`	`training-verification.verifications.events`	read
`GET /verifications/{id}/certificate`	`training-verification.verifications.certificate`	read
`GET /verifications/{id}/report`	`training-verification.verifications.report`	read
`POST /verifications/{id}/cancel`	`training-verification.verifications.cancel`	write

Dates are ISO 8601 UTC with a Z. The dates of the courses found are UK dates, YYYY-MM-DD. Money is whole pence with currency GBP.

Quickstart in a sandbox

A sandbox is a private copy of the Hub API with made-up data: nothing you do in it charges a real account or sends a real email. This takes about five minutes.

Create a sandbox and a test key

In the console choose Sandboxes, then New sandbox, and API keys, then New key for that sandbox. A test key starts with hbk_test_ and is shown once. See Sandboxes and API keys and tokens.

Exchange the key for a token

Bash

BASE="https://<developer-site>/sandbox/<sandbox-id>/api/v2"
KEY="hbk_test_YOUR_TEST_KEY"
TOKEN=$(curl -s -X POST "$BASE/auth/token" \
  -H "Content-Type: application/json" \
  -d "{\"api_key\": \"$KEY\"}" | jq -r .access_token)

Check the account and its prices

Bash

curl -s "$BASE/training-verification/profile" -H "Authorization: Bearer $TOKEN"

The sandbox account is a regular one: automated verification is free, manual verification costs 12 pounds with VAT.

Send a certificate

Bash

curl -s -X POST "$BASE/training-verification/verifications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: quickstart-1" \
  -F request_type=auto \
  -F candidate_name="Jo Smith" \
  -F [email protected] \
  -F agency_name_on_cert="Healthy Staffing Ltd" \
  -F client_reference=PLACEMENT-2291 \
  -F [email protected]

The answer is 202 with status pending and the id of the verification. The same call with the certificate as base64 JSON is on Submitting a certificate.

Watch it move

A few seconds later it is processing, and half a minute after that verified:

Bash

curl -s "$BASE/training-verification/verifications/VERIFICATION_ID" -H "Authorization: Bearer $TOKEN"
curl -s "$BASE/training-verification/verifications/VERIFICATION_ID/events" -H "Authorization: Bearer $TOKEN"

A verified answer carries result.records, the courses found. Add a webhook endpoint in the console first and you also receive training-verification.submitted, .processing and .verified (Webhooks).

Download the report, then try a failure

Bash

curl -s "$BASE/training-verification/verifications/VERIFICATION_ID/report" \
  -H "Authorization: Bearer $TOKEN" -o report.pdf

Send a file called jo-not-found.pdf to get a not_found outcome instead. Sandbox behaviour shows every way to steer the outcome.

Where to go next

Who pays for what: prices, credits, balances and the 402 error

Submitting a certificate: formats, limits, multipart and base64, examples in five languages

Statuses and results: the status set, the result and the reason codes

Webhooks: the seven events and their payloads

Errors and Sandbox behaviour