Connect Your Student System to the Testing Center — Setup Guide

This guide is for the person setting things up — a coordinator, an administrator or a project manager. You do not need to know how to program. By the end you will have created a test link for a pretend student, opened it as that student and seen the result come back. Then you hand over to your developers.

Developers: the technical details are in Testing Center API — Reference.

What this does

Your school already has a student system (an SIS — the software where your students, classes and grades live). This connection lets that system give any student a PrepareBuddy test without the student creating an account or remembering a password:

 Your student system                     PrepareBuddy
 ───────────────────                     ────────────
 1. "Student 00001 needs test A1"  ───▶  makes a personal test link
                                   ◀───  https://…/language-tests/start/?code=7KQ2M9XPRA
 2. Sends the link to the student
    (email, SMS, or inside your system)
                                         3. Student opens the link, presses Start, takes the test
                                         4. The result is ready (straight away, or after a teacher checks it)
 5. Gets the result                ◀───  sent automatically, or fetched whenever you ask
    (score, CEFR level, date)

Your student system only ever sends PrepareBuddy a student ID (like 00001). It does not need to send names, emails or phone numbers.

Words you will see

Who does what

You need to be an administrator (or examiner) of your organization in PrepareBuddy. If you are trying this in a sandbox organization first, everything below works the same way there — and sandbox tests are not billed.

Step 1 — Create the sitting

1. Sign in to PrepareBuddy and go to Language Tests → Testing Center.
2. Choose your organization, then click Conduct a test.
3. Step 1 — Pick the test your students will take (for example a CEFR placement test).
4. Step 2 — Who takes it? In Assessment ID for your student system, type the ID your student system will use — for example A1-midterm. You can leave Candidates empty: your student system will add the students.
5. Set the window — when the sitting opens and the last moment a student can start ("take by"). A student who has already started is never thrown out when the window closes.
6. Step 3 — How are results released?
7. Release results immediately — the student and your system get the result as soon as it is scored.
8. Examiner review before release — a teacher checks (and can adjust) writing and speaking first. Your system receives the result when the teacher releases it.
9. Click Create event.

Rules for an assessment ID: 1–64 characters; letters, digits and . _ - / : @ # +; no spaces. Each ID can be used by only one sitting at a time in your organization. Capital letters matter: A1 and a1 are different.

Already have a sitting? Open it, click Connect your student system (API), type the assessment ID and click Save. Leave the box empty and save to disconnect — links already sent keep working.

Step 2 — Decide how you will name assessments

Agree one naming pattern with your team and your developers, and stick to it. We recommend one ID per level and term, for example:

Starting a new term? Create the new sitting with a new ID (A1-MID-2026T2) and tell your developers. If you prefer to keep the same ID every term, open the new sitting and save the old ID there: PrepareBuddy moves it from the old sitting automatically, and students sent from then on get the new sitting.

Step 3 — Create an API key

1. Open Organization dashboard → API Keys & Integrations.
2. Name the key, for example Student system – production (or – sandbox).
3. Access: Full access. (Read-only keys can fetch results but cannot create test links.)
4. Click Create key and copy it immediately — it is shown only once.
5. Store it like a password. Send it to your developers through a password manager or another secure channel — never in a normal email or chat message.

If a key is ever exposed, click Revoke and create a new one. Revoked keys stop working instantly.

Step 4 — Make a test link yourself (with Postman, no coding)

Postman is a free app for sending requests to an API by filling in boxes.

Shortcut — our ready-made requests. In Postman choose Import → Link and paste https://www.preparebuddy.com/static/integrations/preparebuddy-testing-center-api.postman_collection.json. Click the imported collection → Variables, fill in api_key, assessment_id and student_id, save, and run requests 1 → 9 in order. Or follow the manual steps below — they do the same thing.

1. Install Postman from postman.com and open it.
2. Click New → HTTP Request.
3. Change GET to POST, and paste this address: https://www.preparebuddy.com/api/v1/testing-center/attempts/
4. Headers tab → add a row: Key X-API-Key, Value = your API key.
5. Body tab → choose raw, then JSON in the drop-down, and paste:

{
  "student_id": "TEST-001",
  "assessment_id": "A1-midterm"
}

(Use the assessment ID you chose in Step 1.)

1. Click Send. You should see status 201 Created and an answer like this:

{
  "status": "ok",
  "created": true,
  "attempt": {
    "attempt_id": "7c1e9f3a-2b4d-4e8f-9a1b-3c5d7e9f1a2b",
    "student_id": "TEST-001",
    "assessment_id": "A1-midterm",
    "attempt_number": 1,
    "status": "not_started",
    "assessment_url": "https://www.preparebuddy.com/language-tests/start/?code=7KQ2M9XPRA",
    "access_code": "7KQ2M9XPRA",
    "opens_at": null,
    "closes_at": "2026-11-30T23:59:00+00:00",
    "score": null,
    "level": null
  }
}

(The real answer has a few more lines; the important ones are shown.)

1. Click Send again. This time you get 200 OK, "created": false and the same link. That is on purpose: if your student system sends the same student twice, the student still has one link.

Your organization has its own PrepareBuddy address? Use it instead of www.preparebuddy.com everywhere. The links you receive will use the same address you called.

Step 5 — Open the link as the student

1. Copy the assessment_url and open it in a private (Incognito) browser window, so it does not mix with your own PrepareBuddy login.
2. You see "Your test is ready" with the access code already filled in. Press Start test.
3. You are now inside that one test — nothing else in PrepareBuddy is reachable with this link.
4. To finish quickly while trying things out, start the test and use Exit / Submit. Whatever has been answered is scored.

What the student never has to do: register, choose a password, confirm an email address or remember a username. If they close the browser and open the link again, they continue where they were. After finishing, the same link shows them their result once it is released.

Step 6 — See the result

In PrepareBuddy: open the sitting (Testing Center → your sitting). TEST-001 is listed like any other candidate, with status, score and level. If you chose examiner review, the result appears under awaiting review until a teacher releases it.

Through the API (in Postman):

1. New request, GET, address: https://www.preparebuddy.com/api/v1/testing-center/students/TEST-001/results/
2. Same X-API-Key header. Click Send.

{
  "status": "ok",
  "count": 1,
  "attempts": [
    {
      "attempt_id": "7c1e9f3a-2b4d-4e8f-9a1b-3c5d7e9f1a2b",
      "student_id": "TEST-001",
      "assessment_id": "A1-midterm",
      "status": "completed",
      "score": 62,
      "max_score": 100,
      "percentage": 62.0,
      "level": "B1",
      "completed_at": "2026-10-23T14:30:00+00:00"
    }
  ]
}

What the status means:

level is the CEFR level the test awarded (for example B1). It is empty for tests that do not award a level, and when the student answered too little to be placed — then result_note says why (for example "0 of 54 questions answered"). A pretend student who presses Exit straight away gets exactly that.

Step 7 — Get results sent automatically (webhook)

Instead of asking for results, your student system can be told when something happens.

1. Ask your developers for the webhook address of your student system (it starts with https://). Just trying things out? A free request-inspection site such as webhook.site gives you a temporary address where you can watch events arrive — use it only with pretend students like TEST-001.
2. Open Organization dashboard → API Keys & Integrations → Manage webhooks.
3. Paste the address. Under Send these events, tick the Testing Center API events:
4. attempt.completed — the result is final (the important one)
5. attempt.submitted — finished, waiting for review (optional)
6. attempt.started, attempt.expired, attempt.cancelled (optional)
7. Click Add webhook, then copy the signing secret and give it to your developers the same secure way as the API key.
8. Click Send test — a test event arrives within seconds.

Status changes are sent within about 5 minutes. If a result is re-marked later (a teacher adjusts a score), attempt.completed is sent again with the new score.

Step 8 — Hand over to your developers

Send them:

1. The link to Testing Center API — Reference.
2. The API key and webhook signing secret — through a secure channel.
3. Your list of assessment IDs and what each one means.
4. The base address (for example https://www.preparebuddy.com, or your own PrepareBuddy address).
5. Whether each sitting releases results immediately or after review.

Everyday tasks

Questions

Do students need an email address? No. They need only the link.

Can a student share their link? Anyone with the link can take that one test as that student — the same as a password or a printed access slip. Ask your system to send links only to the student. If a link leaks, issue a new one.

Can the link be used to get into anything else? No. It opens only that student's test and result.

What if your system sends the same student twice? Same attempt, same link. Nothing is duplicated.

What does it cost? Each sitting a student completes counts as one test under your agreement. Links that are never used are not charged. Sandbox organizations are not billed.

Can teachers see the students in PrepareBuddy? Yes — each sitting lists its students by student ID, with status, score and level, plus the usual exports, certificates and review tools.

If something goes wrong