Backend API: Creating Exam Sessions and Getting Tokens

Endpoint

POST

https://api.trustexam.ai/api/external-session/assignment.json?api_token=YOUR_API_TOKEN

You can also pass api_token in the request headers:

• Header: X-Authorization: YOUR_API_TOKEN
  
  

Response (Key Field)

From the JSON response, you need only one field to start the proctoring session:

{
  "external_session": {
    "token": "..."
  },
  "report_url": "https://app.trustexam.ai/.../report"
}

{
  "external_session": {
    "token": "..."
  },
  "report_url": "https://app.trustexam.ai/.../report"
}

{
  "external_session": {
    "token": "..."
  },
  "report_url": "https://app.trustexam.ai/.../report"
}

• external_session.token – used by the frontend SDK.

• report_url – URL where you can view the attempt report in the TrustExam UI.

Required Structure

The request body is a JSON object with at least these sections:

1. assignment (object) – REQUIRED

• assignment.external_id (string / int / mixed) – required

  Unique identifier for the exam/assignment in your system.

  
  Examples:

  • "platonus-2025-09-17"

  • "subject-math-101"

  This ID is used to:

  • group attempts,

  • update exam settings without creating duplicates,

  • re-use the same assignment for multiple students.

• assignment.name (string) – required

  Human-readable exam name.

  Examples:

  • "Exams for 2025-09-17"

  • "Financial Literacy"

• assignment.settings (object) – required

  Contains:

  • proctoring_settings – all proctoring configuration

  • webhook – webhook settings (optional, see below)
    
    

2. student (object) – REQUIRED

• student.external_id (string / int / mixed) – required

  Your internal user ID. If you send the same student.external_id and assignment.external_id again, TrustExam will update the record instead of creating duplicates.
  
  

• student.name (string) – required

  Full name of the student.
  
  

• student.email (string) – recommended

  Used for notifications or linking accounts.
  
  

3. application (string) – REQUIRED

• Possible values: "desktop", "tray", "browser"

• Default: "browser"

  Select the application type used for this exam.

4. session_data (object) – OPTIONAL

• session_data.external_id (string / int / mixed)

  An ID for the specific exam attempt in your system.

  It will return in reports as:

  • assignment_attempt_external_id (Default report), or

  • attemptId (HRTools format).
    
    

Webhook Settings (assignment.settings.webhook)

You can configure webhooks to receive updates when an exam starts or finishes.

• webhook.report_type (string)

  Default: "Default"

  Possible values: "Default", "HRTools" (custom formats may be added).
  
  

• webhook.start_url (string, optional)

  URL that TrustExam will call when the exam starts.

  Example: https://your-domain.com/webhook/start
  
  

• webhook.finish_url (string, optional)

  URL that TrustExam will call when the exam finishes.

  Example: https://your-domain.com/webhook/finish
  
  

• webhook.post (object, optional)

  Arbitrary JSON that will be included in the webhook body.

  Example:

  {"course_id": 123, "instructor_id": 456}
  
  

• webhook.headers (object, optional)

  Custom HTTP headers for webhook calls.

  Example:
  {"Authorization": "Bearer token", "X-Custom-Header": "value"}
  
  

• webhook.query (object, optional)

  Additional URL query parameters.

  Example:
  {"version": "1.0", "format": "json"}

Summary of Backend Flow

1. Your backend calls the TrustExam API with assignment + student data and optional settings.
   
   

2. TrustExam returns external_session.token and report_url.
   
   

3. You pass external_session.token to your frontend and initialize the Proctoring SDK.
   
   

4. Exam events are available via:

   • webhooks,

   • report_url,

   • AI reports API.