How to connect to the API

Four calls from your server: three open a practice test from your own page, and one brings the results back. Plain HTTPS with JSON bodies and a bearer key.

Before you start

Your server makes every call, so a key never reaches a browser. The organisation comes from the key itself.

Base URL
https://tutordash.io
Authentication
Authorization: Bearer tdr_…
Format
JSON request and response bodies over HTTPS
Sandbox
A sandbox key works against our staging environment, which is separate from live student data.
Test IDs
Open the practice test in TutorDash. The ID is the last part of its address, /practice-tests/<id>, and it stays the same when the test's content is corrected.

Two keys

KeyWhat it doesLifetime
Course launchCreates students, reads which buttons to show and opens tests. Used by the three launch calls.Works until revoked.
ReportingRead-only. Used by the results export.Expires after 90 days.

An organisation administrator creates and revokes both in Settings, under Reporting. A Reporting key does not open tests, and a Course launch key does not read reports.

1Create the student

POST/api/partner/v1/students

Send your own permanent ID for the learner, with their name and email. The first call creates the student and their login silently. No email goes out. Later calls update the name and email.

Returns. 201 with created: true the first time, 200 with created: false after that.

Request
POST /api/partner/v1/students
Authorization: Bearer tdr_…
Content-Type: application/json

{
  "external_id": "learner-1042",
  "email": "student@example.com",
  "name": "Sam Student",
  "test_preference": "act",
  "match_existing_email": false
}
Response201 Created
{
  "student_id": "<student uuid>",
  "external_id": "learner-1042",
  "created": true
}
  • external_id is 1 to 120 characters: letters, digits and . _ : @ -
  • Keep student_id: it is the key in every export.
  • With match_existing_email false, siblings who share an email stay separate students.
  • test_preference is sat or act, and defaults to sat.

2Ask which buttons to show

POST/api/partner/v1/status

One call per page view, after the students call, for up to 50 tests. The reply is the exact button set for each test: start, resume, or retake and review, with scores once a test is finished.

Returns. For each test: its status, the actions to show as buttons, the sitting in progress or completed, and the path of the score report.

Request
POST /api/partner/v1/status
Authorization: Bearer tdr_…
Content-Type: application/json

{
  "external_id": "learner-1042",
  "test_ids": ["<test uuid>"]
}
Response200 OK
{
  "student_id": "<student uuid>",
  "external_id": "learner-1042",
  "tests": [
    {
      "test_id": "<test uuid>",
      "title": "ACT Practice Test 1",
      "test_suite": "act",
      "status": "completed",
      "actions": ["retake", "review"],
      "in_progress": null,
      "completed": {
        "attempt_id": "<attempt uuid>",
        "started_at": "…",
        "completed_at": "…",
        "raw_scores": { "english": 61 },
        "scaled_scores": { "english": 27 },
        "composite_score": 27,
        "score_estimated": false
      },
      "review_path": "/practice-tests/<test uuid>/attempt/<attempt uuid>/results"
    }
  ]
}
  • status is not_started, in_progress, completed or unavailable.
  • actions is start; resume; retake plus review; or resume plus review when a retake is under way.
  • Scaled scores and the composite are null until the test has a score conversion table.
  • A 404 means the external_id is unknown: create the student first.

3Open the test

POST/api/partner/v1/launch

When the student clicks, ask for a launch link and send their browser to it with a 303 redirect. The link works once, for two minutes, and only for that button.

Returns. launch_url and expires_in_seconds.

Request
POST /api/partner/v1/launch
Authorization: Bearer tdr_…
Content-Type: application/json

{
  "external_id": "learner-1042",
  "test_id": "<test uuid>",
  "action": "start",
  "return_url": "https://courses.example.com/account/tests"
}
Response200 OK
{
  "launch_url": "https://tutordash.io/launch#<one-use token>",
  "expires_in_seconds": 120
}
  • action is start, resume, review or retake.
  • A 409 means the button is stale, for example the student finished the test in another tab: read status again and re-render.
  • return_url is optional: an https address of up to 2,048 characters, the course page the student clicked on. TutorDash keeps it for a day and shows a Back to your organisation link in its navigation and on the score report.

4Read the results

GET/api/reporting/v2/attempts

Pull every practice-test sitting of your organisation, assigned or self-started, retakes included, in order of last change. This call uses the Reporting key. Rows carry the IDs you sent, so they join to your own records.

Returns. data, one row per sitting with raw scores, scaled scores, the composite and one entry per question; and meta, with the watermark and the next cursor.

Request
GET /api/reporting/v2/attempts?updated_since=2026-11-01T00:00:00.000Z
Authorization: Bearer tdr_…
Response200 OK
{
  "data": [
    {
      "id": "<attempt uuid>",
      "student_id": "<student uuid>",
      "external_ids": ["learner-1042"],
      "assessment_id": "<test uuid>",
      "test_suite": "act",
      "completed_at": "…",
      "raw_scores": { "english": 61 },
      "scaled_scores": { "english": 27 },
      "composite_score": 27,
      "items": [
        {
          "question_number": 1,
          "section": "english",
          "domain": "<domain>",
          "skill": "<skill>",
          "answered": true,
          "correct": true,
          "time_spent_seconds": 38
        }
      ]
    }
  ],
  "meta": {
    "version": 2,
    "resource": "attempts",
    "watermark": "…",
    "next_cursor": "<cursor>"
  }
}
  • The response is trimmed here. Each question entry also carries difficulty and the review mark.
  • Follow meta.next_cursor until it is null and keep meta.watermark for the next run's updated_since.
  • Filter by assessment_id, student_id, test_suite, completed_from and completed_to. Timestamps are UTC with milliseconds.
  • Sittings in progress have no scores and no question entries.
  • There is no completion webhook: your job pulls.

Paging, and the same page as CSV

A page holds up to 100 attempts or 4 MiB, whichever comes first. Add format=csv for one line per question, with the attempt columns repeated.

JSON
GET /api/reporting/v2/attempts?limit=100&cursor=<cursor>
Authorization: Bearer tdr_…

{
  "data": [ … up to 100 attempts … ],
  "meta": {
    "version": 2,
    "resource": "attempts",
    "organization_id": "<organisation uuid>",
    "completed_from": null,
    "completed_to": null,
    "watermark": "…",
    "next_cursor": null
  }
}
  • JSON: follow meta.next_cursor until it is null, and keep meta.watermark.
  • CSV: follow the X-Next-Cursor header until it is absent, and keep X-Watermark.
  • Keep the same filters while paging. Deduplicate by attempt ID and question ID.
  • A sitting without a stored question snapshot is one CSV line with empty question columns.

There are also weekly resources for students, classes, assignments, assessments, sections, attempts and skills, on the same key, under /api/reporting/v1 with a required week parameter.

What the student sees

The launch link signs the student in and opens the right screen for the button they clicked.

start, retake
The test's start page, where the student picks standard, 1.5×, 2× or 3× time and break time.
resume
The sitting, where they left off.
review
The score report.
  • The link signs in the student it was made for. No password, no email.
  • A sibling signed in on the same browser is switched to the right student.
  • A tutor's or administrator's session is never switched. The page asks them to sign out first.
  • If TutorDash is busy, the launch page waits and retries before asking the student to reopen the test.

Errors

The launch API answers with these statuses. 404, 409 and 410 are expected in normal use.

StatusMeaning
400Invalid body. The message names the field.
401Missing, expired, revoked or wrong-type key.
402The organisation's plan or trial has lapsed.
403Redemption from another origin, or a staff account is signed in on that browser.
404Unknown operation, student or test.
409Stale button, or a student without a usable login.
410Launch link expired or already used.
429Over the request throttle.
503TutorDash could not complete the request. Retry.

The reporting export answers 400 for an invalid request or cursor, 401 for a key that is missing, revoked or expired, 402 when the plan or trial has lapsed, 413 for a single record too large for a page, 429 when throttled and 503 for a temporary failure. Retry failures with backoff, and never treat an error as an empty result.

Planning a large cohort or a launch day? Tell us your expected peak launches and weekly exports before you load test.

WordPress helper

If your student site runs on WordPress, you do not have to start from a blank file. We have a PHP helper that makes the three launch calls from a course template.

WordPress template
<?php
// wp-config.php, never in a template or the browser
define('TD_PARTNER_KEY', 'tdr_…');

// In your course template, after your own enrolment
// check and before any output.
// $tests maps a TutorDash test ID to your label for it.
$tests = array('<test uuid>' => 'Practice Test 1');
td_prepare_course($learner_id, $email, $name, $tests);

// Where the buttons go
td_buttons($learner_id, $tests);
  • Renders the button set for every test on the page from one status call
  • Turns a click into a one-use launch link and a 303 redirect
  • Binds each form to the learner and the test, and rejects test IDs you did not list
  • Remembers for a day that a learner is already set up, so most page views skip the students call

It was written for one course site, so the part that finds the current learner needs adapting to yours. Keep your own enrolment check on every request, keep the key in private server config, and leave the course page out of full-page caching. Ask for the file with your sandbox key.

Keys and security

Student records stay in TutorDash. Your site keeps its own records and joins them by the ID you chose.

Keys stay on your server
A key travels only in the Authorization header of a server-to-server request. Keep it out of URLs, browser code, logs and shared files. It is shown once, when it is created.
Two keys, least access
A Reporting key only reads, and expires after 90 days. A Course launch key creates students, opens tests and reads status, and works until revoked. Neither can publish tests, send messages or change billing.
One organisation per key
The organisation comes from the key itself, so a key only ever sees its own organisation's data. It stops working if the administrator who created it loses that role.
Launch links are single use
Each link works once, for two minutes, and only for the button it was made for. The token travels in the URL fragment, so it does not reach server logs.
Staff sessions are never switched
A launch link signs in the student it was made for. It can replace another student's session on the same browser, never a tutor's or an administrator's.
The export leaves content out
Reporting returns scores and per-question outcomes. It excludes question text, answer keys, explanations, the answers students entered, contact details and billing data.
If a key leaks
An administrator revokes it in Settings, under Reporting, and creates a new one. A revoked key stops working immediately. After creation only the last four characters are listed.

Ready to build

Ask for a sandbox key and make your first call against our staging environment.