JavaScript SDK

The @alot/sdk package lets you integrate ALOT into your own product — pull assessment results, list candidates, or embed the assessment flow — all from your server.

Installation

npm install @alot/sdk
# or
pnpm add @alot/sdk

Initialization

import { AlotClient } from '@alot/sdk'

const alot = new AlotClient({
  apiKey: process.env.ALOT_API_KEY!,
  // baseUrl defaults to https://api.yourdomain.com/v1
  baseUrl: 'https://api.yourdomain.com/v1',
})

Assessments

// List published assessments
const { items, total } = await alot.assessments.list({ page: 1, limit: 10 })

// Get a single assessment with stages
const assessment = await alot.assessments.get('assessment_id')

// List candidates for an assessment
const { items: candidates } = await alot.assessments.candidates('assessment_id', {
  status: 'COMPLETED',
  page: 1,
})

Candidates

// List all candidate sessions across assessments
const { items } = await alot.candidates.list({ status: 'COMPLETED' })

// Get a specific session
const session = await alot.candidates.get('session_id')

Results

// Exchange a result token (from ?result= query param) for the full result
const result = await alot.results.fromToken(resultToken)

// Or fetch directly by session ID (requires results:read scope)
const result = await alot.results.fromSession('session_id')

Error handling

import { AlotApiError } from '@alot/sdk'

try {
  const result = await alot.results.fromToken(token)
} catch (err) {
  if (err instanceof AlotApiError) {
    console.error(err.statusCode, err.message)
  }
}

Example: Post-assessment webhook + SDK

A common pattern is to receive the webhook when a candidate completes, then use the SDK to fetch the full result:

// Your webhook handler (Express / Next.js API route)
import { AlotClient } from '@alot/sdk'
import crypto from 'crypto'

const alot = new AlotClient({ apiKey: process.env.ALOT_API_KEY! })

export async function POST(req: Request) {
  const body = await req.text()
  const sig = req.headers.get('x-alot-signature')
  
  // Verify HMAC-SHA256 signature
  const expected = crypto
    .createHmac('sha256', process.env.ALOT_WEBHOOK_SECRET!)
    .update(body)
    .digest('hex')
  
  if (sig !== `sha256=${expected}`) {
    return new Response('Unauthorized', { status: 401 })
  }

  const event = JSON.parse(body)
  
  if (event.type === 'candidate.completed') {
    const session = await alot.candidates.get(event.data.sessionId)
    console.log('Score:', session.score)
    // Sync to your ATS, Notion, Slack, etc.
  }

  return new Response('ok')
}