Exam Feedback Integration Guide
Submit exam responses to receive AI feedback and weakness reports
Getting Started
Once a learner finishes an exam and it has been scored, send their responses to receive per-question AI feedback and a weakness report for that attempt.
Writing and Speaking are submitted through separate APIs.
Overview
Sending One Attempt
A single learner's attempt is submitted by section.
| Step | API | Content |
|---|---|---|
| 1 | POST /api/v1/courses/exam-gradings/writing | Writing, 12 questions with their responses |
| 2 | POST /api/v1/courses/exam-gradings/speaking | Speaking, 11 questions with their responses |
| 3 | GET /api/v1/courses/exam-gradings/{job_id} | Retrieve the result for each question |
One job is created per item in items.
You send the scores, we write the feedback
Both the question score and the section score are required. We do not re-score the response; we display what you send. The feedback names what the response did well and what to fix, against the ETS scoring guides.
| Field | Range | Notes |
|---|---|---|
| items[].score | 0 - 5 | Question score. Build a Sentence is 0 or 1 |
| section_score | 1.0 - 6.0 | Section score, in steps of 0.5 |
Both are required. A request without them is rejected.
Weakness Reports
Once every question in a section has been graded, the weakness report for that attempt is created automatically. No separate request is needed.
| Section | Questions | Report is created |
|---|---|---|
| Writing | 12 | when all 12 questions are graded |
| Speaking | 11 | when all 11 questions are graded |
No report is created if questions are missing. Send every question of an attempt.
When the same weakness is flagged again in a later attempt, its cumulative count is shown alongside it.
What the diagnosis is built from
Every time a question is graded, a tag records which criterion the response fell short on. Tags come from a fixed list per question type.
| Question type | Weakness tags |
|---|---|
| Build a Sentence | 어순 오류 / 문법 표지 오류 / 어휘 선택 / 미응답 |
| Write an Email | 과제 수행 / 내용 전개 / 문장 구조 / 어휘 선택 / 격식과 표현 관습 / 문법 정확성 / 철자와 표기 |
| Academic Discussion | 과제 수행 / 근거와 예시 / 내용 전개 / 문장 구조 / 어휘 선택 / 문법 정확성 |
| Listen and Repeat | 재현 정확도 / 내용어 누락 / 문법 표지 오류 / 어순 오류 / 발화 완결성 / 발화 분량 |
| Take an Interview | 질문 대응 / 내용 전개 / 문장 연결 / 발화 속도와 휴지 / 문법 정확성 / 어휘 선택 |
Speaking responses are also analysed as audio. Four delivery axes are scored 0 to 5, and any axis at or below 2 is added to the weaknesses.
| Axis | What it looks at |
|---|---|
| 발음 정확도 | Whether words come out recognisably |
| 강세와 리듬 | Whether content words carry stress and the speech flows |
| 억양 | Whether pitch moves within a sentence |
| 발화 속도와 휴지 | Whether pace is even and pauses are purposeful (Take an Interview only) |
Ranking follows frequency
Tags are counted across the attempt and the five most frequent are kept. A criterion that keeps coming up is the biggest thing costing points that attempt. The number on screen is that rank, and rank 1 is what to fix first.
| Rank | Weakness | Questions affected |
|---|---|---|
| 1 | 철자와 표기 | 7 of 12 questions |
| 2 | 문장 구조 | 5 questions |
| 3 | 어휘 선택 | 4 questions |
Each weakness has two parts. The diagnosis says what is going wrong and why, with an example drawn from the learner's own answer. The tip gives one thing they can practise alone: what to do, how, and how much.
The summary names only the single biggest factor rather than repeating the list below it, in 100 characters or fewer.
Checking whether it is ready
The weakness_report field in the grading result response tells you whether that section's diagnosis exists yet. It turns READY once every question in the section is graded.
| Value | Meaning |
|---|---|
| PENDING | Some questions in the section are still ungraded |
| READY | The diagnosis exists and can be fetched |
Writing and Speaking are counted separately. Finishing all 12 Writing questions leaves Speaking at PENDING until its own questions are graded.
The Server Counts Attempts
There is no need to send an attempt number. When a report is created, the server counts the learner's existing reports to assign one.
| Sent | exam_id | Attempt assigned |
|---|---|---|
| First | I100000760_1 | 1 |
| Second | I100000769_1 | 2 |
| Third | I100000771_1 | 3 |
Resending the Same Exam
The same exam_id, user_id and problem_id combination is treated as one grading, and it keeps the attempt number it was first given.