Deep Dive: Creating Exam Deliveries via the Scorpion API

This guide provides an in‑depth walkthrough of how to create exam deliveries programmatically using the Scorpion API. It includes endpoint details, required/optional body fields, example payloads, cURL samples, Postman examples, and best practices.

1. Overview

Creating an exam delivery via API allows you to programmatically register candidates, generate launch tokens, manage retakes, select specific forms, and attach metadata.

This process requires: - A Scorpion App with proper CRUD Delivery permissions - Your Basic Authorization Token from the App Settings - An exam_id from the Scorpion UI

This API call is the heart of automated delivery creation.

2. Endpoint

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

Authentication is handled using your App’s Basic Authorization Token.

Header:

Authorization: Basic <YourBasicAuthToken> 
Content-Type: application/json

3. Required Field: examinee_info

At minimum, your POST body must contain the examinee_info object.

Example

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

This schema must match the exact Examinee Info fields defined in your Scorpion project.

4. Optional Fields

Optional fields allow you to control retakes, cross‑project identity, form selection, and metadata.

4.1 examinee_id

Use this to: - Assign a retake to the same examinee within the same project - Maintain form rotation logic defined in the Scorpion project

Example

{ 
  "examinee_id": "<UUID>", 
  "examinee_info": { ... } 
}
 

4.2 external_id

Behaves like examinee_id but works across projects.

Useful when you have multiple exam titles and want a global identity.

Example

{ 
  "external_id": "candidate-12345", 
  "examinee_info": { ... } 
}
 

4.3 form_id

Overrides Scorpion’s automatic form assignment.

Use this when you want to force a specific form.

{ 
  "form_id": "<form_uuid>", 
  "examinee_info": { ... } 
}
 

4.4 meta

Allows you to attach custom metadata to the delivery.

{ 
  "examinee_info": { ... }, 
  "meta": { 
    "course": "Intro to API Automation", 
    "session": "Fall 2025" 
  } 
}

5. Example Response

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

Launch URL

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

Proctor URL

https://scorpion.caveon.com/proctor/<proctor_token>

6. Creating Deliveries Using Postman

A full Postman collection has been provided containing: - Create Delivery (POST) - Create Proctor Events (POST) - Get Delivery by ID (GET) - Update Delivery (PUT) 
 
POSTMAN COLLECTION INCLUDED AT THE BOTTOM OF THIS ARTICLE

Import the collection

1. Open Postman
2. Click Import
3. Upload the file: Scorpion API Sample Calls “Starter Pack” Postman Collection
4. Your collection will appear in the sidebar
    

Example snippet from the collection

(using the Create New Delivery POST request):

POST https://scorpion.caveon.com/api/exams/{{exam_id}}/deliveries 
Authorization: {{Basic}}

Body:

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

fileciteturn0file0

7. Example cURL Calls

7.1 Minimal Delivery Creation

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

7.2 Retake (same project)

{ 
  "examinee_id": "<UUID>", 
  "examinee_info": { ... } 
}
 

7.3 Global retake (cross‑project)

{ 
  "external_id": "employee-801", 
  "examinee_info": { ... } 
}
 

7.4 Force a specific form

{ 
  "form_id": "<form_uuid>", 
  "examinee_info": { ... } 
}

8. Best Practices

• Use least-access permissions for your Scorpion App.
• Store your Basic token in server-side environment variables.
• Do not embed credentials in client-side applications.
• Log API responses for auditing and troubleshooting.
• Avoid assigning a form_id unless required.
• Use external_id when managing multiple exam titles.

9. Related Deep Dives

• 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