Quickstart

Authentication

Every request carries your organisation key in an X-API-Key header. Keys look like jck_live_… and are issued per organisation. Keep the key server-side — never ship it in browser code.

X-API-Key: jck_live_your_key_here
Content-Type: application/json

1. Start a session

Pick a test by slug (big-five, riasec, eq, …). Pass your own external_user_id to tie the result back to your applicant. You get a signed session_id and the full question set.

curl -X POST https://jobcannon.io/api/v1/assessments \
  -H "X-API-Key: jck_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "test": "big-five", "locale": "en", "external_user_id": "candidate-4821" }'

Response

{
  "session_id": "eyJ0ZXN0Ijoi…",   // signed token — pass to step 3
  "test": "big-five",
  "locale": "en",
  "question_pool": null,
  "total_questions": 50,
  "questions": [
    {
      "index": 0,
      "text": "I am the life of the party.",
      "options": [
        { "value": 0, "label": "Very Inaccurate",       "description": "Not at all like me" },
        { "value": 1, "label": "Moderately Inaccurate", "description": "Somewhat unlike me" },
        { "value": 2, "label": "Neither",               "description": "Neither accurate nor inaccurate" },
        { "value": 3, "label": "Moderately Accurate",   "description": "Somewhat like me" },
        { "value": 4, "label": "Very Accurate",         "description": "Definitely like me" }
      ]
    }
    // … one object per question, up to total_questions
  ]
}

2. Collect answers in your UI

Render the questions however you like inside your own flow. Record the option value the candidate picks for each question, in the order the questions were served. The result is a single array of integer option indices, one per question.

// answers[i] is the chosen option value for questions[i]
const answers = [3, 1, 4, 2, 0, 4, 3, /* … 50 values total … */]

Need the questions again mid-session? GET /api/v1/assessments/{session_id}/questions re-serves the same set.

3. Submit for scoring

Post the answers back with the session_id from step 1. The array length must match total_questions. Scoring runs server-side and the result is persisted under your organisation.

curl -X POST https://jobcannon.io/api/v1/assessments/{session_id}/complete \
  -H "X-API-Key: jck_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "answers": [3, 1, 4, 2, 0, 4, 3 /* …50… */], "external_user_id": "candidate-4821" }'

Response (example)

{
  "result_id": "b7f1c2a4-…",
  "test": "big-five",
  "top_result": "extraversion",
  "scores": {
    "openness": 72,
    "conscientiousness": 64,
    "extraversion": 81,
    "agreeableness": 58,
    "neuroticism": 39
  },
  "question_pool": null,
  "external_user_id": "candidate-4821"
}

Score keys and top_result vary by instrument (Big Five returns the five OCEAN dimensions; RIASEC returns the six Holland codes, and so on). The values above are illustrative.

Errors worth handling

• 401 invalid_api_key — key missing, malformed, or revoked.
• 403 session_org_mismatch — the session belongs to a different key.
• 422 answer_count_mismatch — the answers array length ≠ total_questions.
• 429 rate_limited — back off and retry after the returned reset time.