Assign a test

This is the end-to-end flow. All calls are server-to-server with your API key.

1. List available tests

curl https://api-sg.quippy-lab.com/api/partner/v1/tests \
  -H "Authorization: Bearer qk_live_..."

{
  "data": [
    {
      "testId": "exm_01...",
      "title": "English Entry — Sample A",
      "description": "Entry assessment, four skills",
      "durationMinutes": 60,
      "proctoring": "none",
      "marking": "manual",
      "resultVisibility": "after_review"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Only tests published to your institution are returned — we curate this set with you. resultVisibility tells you in advance which completion experience the student will get (see step 4). Paginate with ?limit= (1–100, default 20) and ?offset=.

2. Create an assignment

curl -X POST https://api-sg.quippy-lab.com/api/partner/v1/assignments \
  -H "Authorization: Bearer qk_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e-..." \
  -d '{
    "externalUserId": "your-sub-123",
    "testId": "exm_01...",
    "user": { "email": "student@example.com", "name": "Jordan Lee" },
    "callbackUrl": "https://portal.example.com/return",
    "metadata": { "cohort": "spring-2026" }
  }'

Field	Required	Notes
`externalUserId`	yes	Your stable user id (≤128 chars). Identity is keyed on this, not email.
`testId`	yes	From step 1.
`user.email`	yes	For display and notifications. Email may change on your side without breaking the mapping.
`user.name`	no	Display name.
`callbackUrl`	yes	HTTPS, on your allowlisted domain.
`dueAt`	no	ISO 8601. The assignment expires if not started by then.
`metadata`	no	Opaque JSON object (≤1 KB), echoed on webhooks and status reads.

Response:

{
  "assignmentId": "pas_01...",
  "status": "assigned",
  "externalUserId": "your-sub-123",
  "testId": "exm_01...",
  "startUrl": "https://procto.quippy-lab.com/verify?examId=exm_01...#token=...",
  "startUrlExpiresAt": "2026-07-30T00:00:00Z",
  "createdAt": "2026-07-23T08:30:00Z"
}

We match or create the Quippy user for your externalUserId automatically — no pre-provisioning needed.

Send an Idempotency-Key header (any unique string) so a retried request after a network blip returns the same assignment instead of creating a duplicate. Reusing a key with a different body returns 409.

3. Send the student in

Render startUrl as your “Start test” button. When the student clicks it, they’re signed in automatically and dropped directly onto the assigned test — no password, no separate Quippy login.

The link is valid until startUrlExpiresAt (default 7 days, never past dueAt). Fetch a fresh one any time from GET /assignments/{id}.
Re-opening it re-enters an in-progress attempt. It does not allow a retake after submission — create a new assignment for that.

4. The student finishes

The completion experience depends on the test’s resultVisibility:

`resultVisibility`	Student sees	Then
`immediate`	Their result	”Return to <you>” button
`after_review`	A “marking in progress” screen	”Return to <you>” button

The return button sends them to your callbackUrl with correlation params appended:

https://portal.example.com/return?partnerAssignmentId=pas_01...&externalUserId=your-sub-123&status=submitted

Treat the return redirect as navigation only — users close tabs and links get replayed. Your source of truth for assignment state is webhooks and GET /assignments/{id}, never the redirect.

5. Receive results

Subscribe a webhook endpoint to get real-time updates. Every event for a Partner API assignment carries your externalUserId, partnerAssignmentId, and metadata echo — see the event catalog.

Event	Fires when
`exam.started`	The student begins the test
`violation.detected`	A critical proctoring violation (proctored tests only)
`exam.completed`	The student submits (carries the auto-marked score)
`grading.done`	Manual / AI marking finishes (for `after_review` tests)

No webhook receiver yet? Poll GET /assignments/{id} — it reports live status and, once available, the result.

Getting Started

SSO

Webhooks

Partner API

API Reference

1. List available tests

2. Create an assignment

3. Send the student in

4. The student finishes

5. Receive results

​1. List available tests

​2. Create an assignment

​3. Send the student in

​4. The student finishes

​5. Receive results

1. List available tests

2. Create an assignment

3. Send the student in

4. The student finishes

5. Receive results