> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userecord.io/llms.txt
> Use this file to discover all available pages before exploring further.

# client.createSession()

> Create a session token for one or more candidates. Call this inside your session endpoint handler.

<Info>
  This is a **Backend SDK method**, not an HTTP endpoint. Call it from your server — never from the browser.
</Info>

## Install

<CodeGroup>
  ```bash Node.js theme={null}
  npm install @recordorg/smartai-assessment-backend
  ```

  ```bash Python theme={null}
  pip install smartai-assessment-backend
  ```
</CodeGroup>

## Initialise

<CodeGroup>
  ```typescript Node.js theme={null}
  const AssessmentClient = require('@recordorg/smartai-assessment-backend');

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

  ```python Python theme={null}
  from smartai_assessment_backend import AssessmentClient
  import os

  client = AssessmentClient(
      api_key=os.getenv("ASSESSMENT_API_KEY"),
      secret_key=os.getenv("ASSESSMENT_SECRET_KEY"),
  )
  ```
</CodeGroup>

***

## Signature

<CodeGroup>
  ```typescript Node.js theme={null}
  client.createSession({ users, recruiterId?, recruiterEmail? }): Promise<SessionToken>
  ```

  ```python Python theme={null}
  client.create_session(
      *,
      users: list,
      recruiter_id: str = None,
      recruiter_email: str = None,
  )
  ```
</CodeGroup>

***

## Parameters

<ParamField body="users" type="array" required>
  Array of candidate objects. Must have at least one item.

  <Expandable title="Each user object" defaultOpen>
    <ParamField body="name" type="string" required>
      Candidate's full name. Shown in the assessment UI and result reports.
    </ParamField>

    <ParamField body="email" type="string" required>
      Candidate's email address. Used as the unique identifier on the SmartAI platform. Match on this when you receive webhook results.
    </ParamField>
  </Expandable>

  ```json Example theme={null}
  [
    { "name": "Priya Sharma",  "email": "priya@example.com" },
    { "name": "Rahul Verma",   "email": "rahul@example.com" }
  ]
  ```
</ParamField>

<ParamField body="recruiterId / recruiter_id" type="string">
  Your internal recruiter ID. You can pass this **or** `recruiterEmail` — at least one is required. You may pass both.
</ParamField>

<ParamField body="recruiterEmail / recruiter_email" type="string">
  The recruiter's email address. You can pass this **or** `recruiterId` — at least one is required. You may pass both.
</ParamField>

***

## Return value

<ResponseField name="token" type="string">
  A session token (JWT). Pass this directly to `AssessmentPortal.open({ token })` in your frontend. Do not cache or store it — request a fresh one every time.
</ResponseField>

***

<RequestExample>
  ```typescript Bulk mode (Node.js) theme={null}
  const session = await client.createSession({
    users: [
      { name: 'Priya Sharma', email: 'priya@example.com' },
      { name: 'Rahul Verma',  email: 'rahul@example.com' },
    ],
    recruiterEmail: 'admin@yourcompany.com',
  });

  console.log(session.token); // → 'eyJhbGci...'
  ```

  ```python Bulk mode (Python) theme={null}
  session = client.create_session(
      users=[
          {"name": "Priya Sharma", "email": "priya@example.com"},
          {"name": "Rahul Verma",  "email": "rahul@example.com"},
      ],
      recruiter_email="admin@yourcompany.com",
  )

  print(session["token"])  # → 'eyJhbGci...'
  ```

  ```typescript With recruiter ID (Node.js) theme={null}
  const session = await client.createSession({
    users: [
      { name: 'Priya Sharma', email: 'priya@example.com' },
    ],
    recruiterId: '122344344533',
  });
  ```

  ```python With recruiter ID (Python) theme={null}
  session = client.create_session(
      users=[{"name": "Priya Sharma", "email": "priya@example.com"}],
      recruiter_id="122344344533",
  )
  ```

  ```typescript Both recruiter fields (Node.js) theme={null}
  const session = await client.createSession({
    users: [
      { name: 'Priya Sharma', email: 'priya@example.com' },
    ],
    recruiterId:    '122344344533',
    recruiterEmail: 'admin@yourcompany.com',
  });
  ```

  ```python Both recruiter fields (Python) theme={null}
  session = client.create_session(
      users=[{"name": "Priya Sharma", "email": "priya@example.com"}],
      recruiter_id="122344344533",
      recruiter_email="admin@yourcompany.com",
  )
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiJzZXNzXzAxIn0.HMAC"
  }
  ```
</ResponseExample>

***

## Error cases

| Condition                                           | Error message                                                              |
| --------------------------------------------------- | -------------------------------------------------------------------------- |
| Neither `recruiterId` nor `recruiterEmail` provided | `Provide at least one of recruiterId or recruiterEmail` — pass one or both |
| `users` is an empty array / list                    | `users must be a non-empty array`                                          |
| `name` missing in single mode                       | `name is required`                                                         |
| `email` missing in single mode                      | `email is required`                                                        |
| Invalid API key                                     | HTTP 401 from SmartAI platform                                             |
| `ASSESSMENT_API_KEY` not set                        | `Missing API key`                                                          |