API Quick Start — Your First Request in 10 Minutes

This page is for people who have never used an API before. By the end you will have fetched your own students' scores from PrepareBuddy, and you will know which of the other guides to read next.

What is an API, in one paragraph?

An API is a web address that returns data instead of a web page. You send a request to an address such as https://www.preparebuddy.com/api/v1/results/, and PrepareBuddy answers with your students' results as text in a format called JSON — which spreadsheets, CRMs and tools like Zapier can read. To prove the request is really from you, every request carries your API key (a long password for programs).

Step 1 — Create an API key

1. Sign in to PrepareBuddy as an organization administrator.
2. Open Organization dashboard → API Keys & Integrations.
3. Type a name such as Google Sheet – results.
4. Choose the Access:
5. Read only — can only fetch data (results, students, reports). Choose this whenever the key is just for reporting. If it ever leaks, nobody can change anything with it.
6. Full access — can also create things (onboard students, assign tests). Only for tools that need to.
7. Click Create key and copy the key immediately — it is shown once. Keep it like a password: never post it in a chat or email, never put it in a web page.

If a key leaks, click Revoke next to it and create a new one. Revoked keys stop working instantly.

Step 2 — Make your first request

Pick one of the three ways below. They all do the same thing.

Option A — Postman (point and click, no typing commands)

1. Install Postman (free) from postman.com and open it.
2. Click New → HTTP Request.
3. Leave the method as GET and paste the address: https://www.preparebuddy.com/api/v1/ping/
4. Open the Headers tab. Add a row: Key X-API-Key, Value = your key.
5. Click Send. You should see:

{ "status": "ok", "organization": "Acme Prep", "organization_slug": "acme-prep" }

1. Change the address to https://www.preparebuddy.com/api/v1/results/?limit=5 and click Send again — these are your five oldest results.

Option B — the command line (Mac, Linux, or Windows 10+)

Open Terminal (Mac) or Command Prompt (Windows) and paste — replacing YOUR_KEY:

curl -H "X-API-Key: YOUR_KEY" https://www.preparebuddy.com/api/v1/ping/

Then:

curl -H "X-API-Key: YOUR_KEY" "https://www.preparebuddy.com/api/v1/results/?limit=5"

(Keep the quotes around any address that contains ? or &.)

Option C — straight into a Google Sheet

Follow Recipe: Scores into Google Sheets — copy one script, press Run, done.

Step 3 — Read the answer

A result looks like this (shortened):

{
  "id": "test:3f8b2c1e-…",
  "student": {"email": "asha.rao@uni.example", "first_name": "Asha"},
  "item": {"title": "IELTS Academic Mock 3", "type": "ielts"},
  "score": 7.5,
  "max_score": 9,
  "percentage": 83.3,
  "completed_at": "2026-09-27T10:15:03+00:00"
}

• score / max_score — on the test's own scale (IELTS out of 9, TOEFL out of 120 …).
• percentage — the same thing out of 100, handy for comparing different tests.
• completed_at — when it finished. Times are in UTC (+00:00). Add &tz=Asia/Kolkata (or your own zone, e.g. Europe/London, America/New_York) to any address to get local times instead.
• id — never changes for this result. If the same id comes back later with a different score, it was re-marked: replace the old row, don't add a new one.

Step 4 — Choose what to build

When something goes wrong

Base address: everywhere in these guides, https://www.preparebuddy.com is the PrepareBuddy address. If your organization uses its own PrepareBuddy address (a custom domain), use that instead. Always include www. — the address without it redirects, and API requests must not be redirected.