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.

English and Arabic

Use locale=ar for Arabic items and plugin configuration, and include locale: "ar" in scoring requests. English is the default. Item IDs, answer values, and scoring remain the same. These product translations have not been independently psychometrically validated in Arabic.

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)