B5ToolsB5Tools
Start free

API reference

The B5Tools API returns a Big Five-based personality type result from Mini-IPIP-20 answers. All responses are JSON and never cached.

Authentication

Send your API key as a bearer token (or the x-api-key header). Keys are scoped and issued per environment (test / live).

Authorization: Bearer b5t_live_XXXXXXXXXXXXXXXX

GET/api/v1/items

Returns the assessment items. Requires scope items:read.

curl https://b5tools.ly/api/v1/items \
  -H "Authorization: Bearer b5t_live_XXXX"

POST/api/v1/score

Scores 20 answers (1–5) and returns the primary result type. Pro keys also receive browser-only trait spectrums and a secondary style. Requires scope score:read. Counts toward your monthly quota.

curl -X POST https://b5tools.ly/api/v1/score \
  -H "Authorization: Bearer b5t_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"answers":[{"itemId":"mini-ipip-e-1","score":4}, ...]}'

POST/api/v1/pair

Compares two people. Requires scope pair:read and a plan with the pairwise feature (Pro).

curl -X POST https://b5tools.ly/api/v1/pair \
  -H "Authorization: Bearer b5t_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"personA":{"answers":[...]},"personB":{"answers":[...]}}'

GET/api/v1/plugin-config

Returns plan-based plugin capabilities, enabled themes/modes, branding, and telemetry support. Requires scope items:read.

POST/api/v1/events

Records metadata-only WordPress plugin funnel events. Requires scope events:write. Existing score-capable keys are accepted for backwards compatibility. Do not send raw answers, emails, names, or trait vectors.

curl -X POST https://b5tools.ly/api/v1/events \
  -H "Authorization: Bearer b5t_live_XXXX" \
  -H "Content-Type: application/json" \
  -d '{"event":"assessment_started","pageUrl":"/personality-test"}'

Errors

Errors return { ok: false, error: { code, message } }. Common codes:

  • unauthorized / invalid_api_key — missing or bad key (401)
  • forbidden_scope / forbidden_origin / forbidden_feature — key lacks access (403)
  • quota_exceeded — monthly plan quota reached (429)
  • missing_answers / invalid_score — malformed input (400)