Skip to main content
POST
/
assessment
/
session
curl --request POST \
  --url https://your-app.com/assessment/session \
  --header 'Authorization: Bearer <recruiter-jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "users": [
      { "name": "Priya Sharma",  "email": "priya@example.com" },
      { "name": "Rahul Verma",   "email": "rahul@example.com" },
      { "name": "Aisha Khan",    "email": "aisha@example.com" }
    ]
  }'

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJzZXNzXzAxIn0.HMAC"
  }
}
You build this endpoint. The path /assessment/session is whatever route you choose in your own app. Internally it calls client.createSession() from the Backend SDK and returns the token to your frontend.

​
How it fits in the flow

Your Frontend (ProfileList.tsx)
    │
    │  POST /assessment/session
    │  { users: [{ name, email }, ...] }
    │
    ▼
Your Backend (this endpoint)
    │
    │  client.createSession({ users, recruiterId?, recruiterEmail? })
    │
    ▼
SmartAI Platform
    │
    │  { token, expiresAt }
    │
    ▼
Your Backend returns { success: true, data: { token, expiresAt } }
    │
    ▼
Your Frontend calls AssessmentPortal.open({ token })

​
Environment variables required

Add these to your server’s .env file before this endpoint will work: 
ASSESSMENT_API_KEY=wc_ak_test_your_key_here
ASSESSMENT_SECRET_KEY=wc_sk_test_your_secret_here
Never put these in your frontend .env. They belong on the server only. Your frontend uses NEXT_PUBLIC_ASSESSMENT_API_KEY (the public API key) separately just to tell the portal which environment to use — the secret key never leaves your server.

​
Request

​
Headers

​
Authorization
string
required
Your app’s authentication token for the logged-in recruiter. Format: Bearer <jwt>. Protect this endpoint so only your own recruiter accounts can call it.
​
Content-Type
string
required
Must be application/json.

​
Body

​
users
array
required
Array of candidate objects to include in this assessment session. Must have at least one item.
[
  { "name": "Priya Sharma",  "email": "priya@example.com" },
  { "name": "Rahul Verma",   "email": "rahul@example.com" },
  { "name": "Aisha Khan",    "email": "aisha@example.com" }
]
​
recruiterId
string
Your internal recruiter ID. Pass this or recruiterEmail — at least one is required.
​
recruiterEmail
string
The recruiter’s email address. Pass this or recruiterId — at least one is required.

​
Response

​
success
boolean
true when the session was created successfully.
​
data
object
curl --request POST \
  --url https://your-app.com/assessment/session \
  --header 'Authorization: Bearer <recruiter-jwt>' \
  --header 'Content-Type: application/json' \
  --data '{
    "users": [
      { "name": "Priya Sharma",  "email": "priya@example.com" },
      { "name": "Rahul Verma",   "email": "rahul@example.com" },
      { "name": "Aisha Khan",    "email": "aisha@example.com" }
    ]
  }'

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJzZXNzXzAxIn0.HMAC"
  }
}

​
Common mistakes

MistakeWhat happensFix
ASSESSMENT_API_KEY not set in .envReturns 500Add the key to your server .env
Sending users: [] empty arrayReturns 400Make sure candidates are selected before calling
Neither recruiterId nor recruiterEmail sentReturns 400Pass at least one recruiter field
Calling this from the browser directlyAPI key exposed in network tabAlways call through your backend
Reusing the same token for a second sessionToken expired errorAlways request a fresh token