Skip to main content

​
What is SmartAI Assessment?

SmartAI Assessment lets you embed a fully-proctored, AI-generated assessment portal directly inside your own application. You install a backend package and a frontend package — the platform handles everything else.
PackageRuns onLanguagePurpose
@recordorg/smartai-assessment-backendYour serverNode.jsCreates session tokens, polls results
smartai-assessment-backendYour serverPythonCreates session tokens, polls results
@recordorg/smartai-assessment-frontendYour web app (browser)JavaScriptOpens the assessment modal in an iframe

​
How the flow works

YOUR APPLICATION
│
├─ 1. Recruiter selects candidates and clicks "SmartAI Assessment"
│
├─ 2. Frontend calls your backend:
│      POST /assessment/session
│      { users: [{ name, email }, ...] }
│
├─ 3. Your backend calls SmartAI SDK:
│      client.createSession({ users, recruiterId?, recruiterEmail? })
│      ◀── { token }
│
├─ 4. Your backend returns the token to the frontend
│
├─ 5. Frontend opens the portal:
│      AssessmentPortal.open({ token, apiKey })
│      ══► full-screen iframe loads — candidate takes the test
│
├─ 6. Candidate finishes the assessment inside the iframe
│
├─ 7. Your backend polls results every 30 s:
│      client.getWebhookEvents({ limit: 50 })
│      ◀── { events, pendingCount }
│
└─ 8. Save results → client.acknowledgeWebhookEvents([...ids])

​
Quick start

​
1. Get your API keys

Log into the SmartAI dashboard and copy your API key and Secret key.
  • Prefix wc_ak_test_ → test / staging environment
  • Any other prefix → live / production environment
ASSESSMENT_API_KEY=wc_ak_test_your_key_here
ASSESSMENT_SECRET_KEY=wc_sk_test_your_secret_here

​
2. Install backend package

npm install @recordorg/smartai-assessment-backend

​
3. Install frontend package

npm install @recordorg/smartai-assessment-frontend

​
4. Add a session endpoint to your backend

const AssessmentClient = require('@recordorg/smartai-assessment-backend');

app.post('/assessment/session', yourAuthMiddleware, async (req, res) => {
  const client = new AssessmentClient({
    apiKey:    process.env.ASSESSMENT_API_KEY,
    secretKey: process.env.ASSESSMENT_SECRET_KEY,
  });

  // users — array of { name, email }
  const { users, recruiterId, recruiterEmail } = req.body;

  if (!users?.length) {
    return res.status(400).json({ success: false, message: 'No candidates provided' });
  }

  if (!recruiterId && !recruiterEmail) {
    return res.status(400).json({ success: false, message: 'Provide at least one of recruiterId or recruiterEmail' });
  }

  const session = await client.createSession({
    users,           // [{ name, email }, ...]
    recruiterId,     // optional — pass one or both
    recruiterEmail,  // optional — pass one or both
  });

  res.json({ success: true, data: session });
});

​
5. Open the portal from your frontend

Add NEXT_PUBLIC_ASSESSMENT_API_KEY to your frontend .env.local: 
NEXT_PUBLIC_ASSESSMENT_API_KEY=wc_ak_test_your_key_here
Then in your component, call your backend first to get the token, then open the portal: 
// 1. Call YOUR backend to get a session token
const response = await assessmentApi.createSession(users);
const token  = response?.data?.token;
const apiKey = process.env.NEXT_PUBLIC_ASSESSMENT_API_KEY;

// 2. Open the portal (dynamic import required for Next.js)
const { default: AssessmentPortal } = await import('@recordorg/smartai-assessment-frontend');

AssessmentPortal.open({
  token,
  apiKey,
  onDone:  () => toast.success('Assessment sent successfully!'),
  onClose: () => {},
  onError: (err: Error) => toast.error(err.message || 'Assessment failed'),
});

​
6. Poll for results in the background

async function pollResults() {
  const client = new AssessmentClient({
    apiKey:    process.env.ASSESSMENT_API_KEY,
    secretKey: process.env.ASSESSMENT_SECRET_KEY,
  });

  const { events } = await client.getWebhookEvents({ limit: 50 });

  for (const event of events) {
    await saveToDatabase(event);
  }

  if (events.length) {
    await client.acknowledgeWebhookEvents(events.map(e => e.eventId));
  }
}

setInterval(pollResults, 30_000);
pollResults();

​
Integration checklist

API key and secret key set as environment variables on your server
Backend session endpoint created and protected by your own auth middleware
Frontend calls your session endpoint before opening the portal
AssessmentPortal.open() receives the token from your backend
onDone and onError callbacks implemented
Background poller running getWebhookEvents() every 30 seconds
Results saved to your database with idempotent upsert on eventId
acknowledgeWebhookEvents() called after every successful save batch