Broad Basics: Creating Exam Deliveries via API

This document outlines how to authenticate, configure app permissions, and create exam deliveries using Scorpion’s API. It includes examples, optional fields, and URL construction guidance for candidate and proctor access. For further deep dive documentation check out:

Retrieving API Credentials – https://support.caveon.com/hc/en-us/articles/43517427257108-Deep-Dive-Retrieving-API-Credentials
App Permissions Deep Dive – https://support.caveon.com/hc/en-us/articles/43517570013844-Deep-Dive-Scorpion-App-Access-Permissions
App Webhooks Deep Dive – https://support.caveon.com/hc/en-us/articles/44671691855380-Deep-Dive-Scorpion-App-Webhooks
App Widgets Deep Dive – https://support.caveon.com/hc/en-us/articles/43517617001620-Deep-Dive-Scorpion-App-Widgets
Creating Deliveries Via API Deep Dive – https://support.caveon.com/hc/en-us/articles/43517770070932-Deep-Dive-Creating-Exam-Deliveries-via-the-Scorpion-API

1. Overview

Use this endpoint to create a new delivery for a specific exam:

POST https://scorpion.caveon.com/api/exams/<exam_id>/deliveries

Replace <exam_id> with the ID of the exam you want to deliver.

2. Creating and Configuring Your App

Before making API calls, you must first create a Scorpion App and configure its permissions.

2.1 Create Your App

Deep Dive: https://support.caveon.com/hc/en-us/articles/43517570013844-Deep-Dive-Scorpion-App-Access-Permissions

Have a C‑TST admin create a new Scorpion CRUD App for you.
Integrate this App into the Scorpion project you intend to access via API.

2.2 Assign App Permissions (Least Access Principle)

Grant only the minimum permissions required.

Action	Permission	Notes
Create deliveries	create	Required for POST calls to create deliveries
Read delivery data	view	Optional; only needed if reading metadata
Proctor deliveries	proctor	Only assign if the app will proctor
Edit delivery info	edit	Rare; avoid unless necessary

Most integrations need only create (and optionally view). Excess permissions should not be granted.

3. Authentication & Authorization

Deep Dive: https://support.caveon.com/hc/en-us/articles/43517570013844-Deep-Dive-Scorpion-App-Access-Permissions

3.1 Basic Authorization Token

To make API calls, authenticate using a Basic Authorization Token generated by a Scorpion App.

How to Obtain Your Basic Token

Open your Scorpion App.
Click Settings → API Credentials.
Click Get API Credentials.
Copy your Basic Authorization Token.

Important: Each time Get API Credentials is clicked, your credentials are regenerated and older tokens stop working.

Example Header

Authorization: Basic <your_basic_token>

4. Making a Delivery Creation Request

4.1 Example Request Body

{
"examinee_info": {
    "First Name": "Amos",
    "Last Name": "Burton",
    "Email": "amos.burton@example.com"
}
}

4.2 Example cURL Request

curl -X POST "https://scorpion.caveon.com/api/exams/<exam_id>/deliveries" \
-H "Content-Type: application/json" \
-H "Authorization: Basic <your_basic_token>" \
-d '{
    "examinee_info": {
      "First Name": "Amos",
      "Last Name": "Burton",
      "Email": "amos.burton@example.com"
    }
}'

5. Response Payload

{
"delivery_id": "40cabced-6377-41cf-9020-befd582fa956",
"examinee_id": "923ca054-59fe-42e8-a06d-74d499d4c31a",
"launch_token": "<token_value>",
"proctor_token": "<token_value>"
}

Token Use

launch_token → Candidate launch URL
proctor_token → Proctor access URL

6. Constructing URLs

6.1 Candidate (Take) URL

Base URL:

https://scorpion.caveon.com/take?launch_token=

Append the launch_token.

6.2 Proctor URL

Base URL:

https://scorpion.caveon.com/proctor/

Append the proctor_token.

7. Additional Optional Fields

You may include extra fields in the POST body to control delivery behavior.

7.1 examinee_id

UUID
Links the delivery to an existing examinee in the project
Enables retake logic and alternate form selection

7.2 external_id

UUID
Behaves like examinee_id but works across multiple projects

7.3 form_id

UUID
Forces a specific form to be delivered
Found in Scorpion’s Form settings

7.4 meta

Custom metadata attached to the delivery.

Example Including meta

{
"examinee_info": {
    "First Name": "Amos",
    "Last Name": "Burton",
    "Email": "amos.burton@example.com"
},
"meta": {
    "sample_meta_value_1": "Meta 1",
    "sample_meta_value_2": "Meta 2"
}
}

8. Error Handling

Common causes of API errors: - Missing or invalid authentication - Missing required examinee_info fields - Invalid or expired Basic Token - Incorrect UUID formats

Ensure you log full error responses for troubleshooting.

Creating Deliveries via API – Deep Dive: https://support.caveon.com/hc/en-us/articles/43517770070932-Deep-Dive-Creating-Exam-Deliveries-via-the-Scorpion-AP

9. Summary

This API allows you to reliably create Scorpion deliveries using secure, permission‑limited apps. Follow least‑access principles, authenticate with your Basic Token, include examinee information, and optionally attach metadata, form IDs, and examinee/external IDs as needed.