Skip to main content

​
Before you start

You’ll need:
  • An Edpire account with at least one published assessment
  • Your organization’s subdomain (e.g., yourorg in yourorg.edpire.com)
  • An API key — you’ll create one in Step 1
Don’t have an account yet? Request access at edpire.com and we’ll get you set up.

​
Step 1 — Create an API key

  1. Go to app.edpire.com → Settings → API Keys
  2. Click Create key
  3. Name it (e.g., My First Integration)
  4. Select the read:results scope
  5. Copy the key — it is shown only once
Your key starts with edp_live_ and cannot be retrieved after closing the modal. Store it in an environment variable immediately.

​
Step 2 — Verify the API is reachable

Call the assessments endpoint to list your published assessments: 
curl https://app.edpire.com/api/v1/assessments \
  -H "Authorization: Bearer edp_live_<your-key>"
Expected response: 
{
  "data": [
    {
      "id": "asmt_xxx",
      "title": "Year 10 Maths Quiz",
      "share_code": "ABC123",
      "status": "published"
    }
  ],
  "meta": { "total": 1, "page": 1, "limit": 20 }
}
Note the share_code — you’ll use it in the next step.
If you get a 401, double-check that you’re passing the full key including the edp_live_ prefix.

​
Step 3 — Send a learner to the assessment

Redirect a learner to Edpire’s hosted assessment player. No backend code beyond generating the URL. 
https://{your-slug}.edpire.com/take/{shareCode}?learner_ref={userId}&return_url=https://yourplatform.com/results
Replace:
  • {your-slug} — your organization subdomain (e.g. maple-high)
  • {shareCode} — the share code from Step 2 (e.g. ABC123)
  • {userId} — your internal user ID for the learner (a stable, immutable database ID)
The learner completes the assessment. When they submit, Edpire redirects them back to your return_url.

​
Step 4 — Read the result

When the learner finishes, Edpire appends query parameters to your return_url: 
https://yourplatform.com/results?submission_id=sub_xxx&score=14&max_score=20
Use submission_id to fetch the full per-question breakdown from your server: 
curl https://app.edpire.com/api/v1/submissions/sub_xxx \
  -H "Authorization: Bearer edp_live_<your-key>"
Response: 
{
  "data": {
    "id": "sub_xxx",
    "learner_ref": "your-user-id",
    "score": 14,
    "max_score": 20,
    "percentage": 70,
    "passed": true,
    "submitted_at": "2026-04-18T10:30:00Z",
    "question_results": [
      {
        "question_id": "q_aaa",
        "sequence_number": 1,
        "points": 2,
        "result": { "correct": true, "score": 2 }
      }
    ]
  }
}
That’s a complete end-to-end integration using Tier 1 — Share Link, the simplest approach.

​
What’s next?

Integration Tiers

Embed the player inline, build a custom UI, or go fully headless.

Webhooks

Get real-time notifications instead of polling the return URL.

Sandbox

Develop against isolated test data — never touch production.

API Reference

Full interactive reference for every endpoint.