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
| Key | What it does | Lifetime |
|---|---|---|
| Course launch | Creates students, reads which buttons to show and opens tests. Used by the three launch calls. | Works until revoked. |
| Reporting | Read-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.
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
}{
"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.
POST /api/partner/v1/status
Authorization: Bearer tdr_…
Content-Type: application/json
{
"external_id": "learner-1042",
"test_ids": ["<test uuid>"]
}{
"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.
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"
}{
"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.
GET /api/reporting/v2/attempts?updated_since=2026-11-01T00:00:00.000Z
Authorization: Bearer tdr_…{
"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.
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
}
}GET /api/reporting/v2/attempts?format=csv&test_suite=act
Authorization: Bearer tdr_…
X-Reporting-Version: 2
X-Watermark: …
X-Next-Cursor: <cursor, absent on the last page>
attempt_id,student_id,external_ids,assessment_id,
assessment_version,test_suite,scope,mode,time_multiplier,
break_multiplier,started_at,completed_at,submitted,
time_spent_seconds,composite_score,section,
section_raw_score,section_scaled_score,question_number,
question_id,domain,skill,difficulty,answered,correct,
question_seconds,marked_for_review,updated_at,
score_estimated- 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.
| Status | Meaning |
|---|---|
400 | Invalid body. The message names the field. |
401 | Missing, expired, revoked or wrong-type key. |
402 | The organisation's plan or trial has lapsed. |
403 | Redemption from another origin, or a staff account is signed in on that browser. |
404 | Unknown operation, student or test. |
409 | Stale button, or a student without a usable login. |
410 | Launch link expired or already used. |
429 | Over the request throttle. |
503 | TutorDash 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.
<?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.