> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truenroll.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluation

> How credentials become evaluated equivalencies, GPA, credits, and reports.

Evaluation converts a credential's academic records into standardized equivalents. You
receive a qualification equivalency, evaluated course grades and credits, and weighted
and unweighted GPA where available.

Document processing and evaluation have separate workflows. After extraction, an operator
reviews and completes evaluation in the TruEnroll UI. The Partner API lets you retrieve
results and reports; it does not start evaluation. Do not include `evaluation` in an
upload's `features` array.

## How evaluation works

<Steps>
  <Step title="Extract and review the credential">
    TruEnroll extracts candidate, institution, qualification, and course information from
    the submitted documents. An operator reviews the extracted data before finalizing
    evaluation.
  </Step>

  <Step title="Apply grade and credit scales">
    The operator selects or reviews the grading scale and credit conversion scale.
    Evaluation maps source grades or marks to equivalent grades and grade points, and
    converts course credits. Course exclusions and retaken courses can affect the results.
  </Step>

  <Step title="Review the equivalency and complete evaluation">
    The operator reviews the qualification equivalency, GPA, credits, and course output.
    The equivalency summary can be edited. Completed evaluations become available through
    the Partner API with any evaluator report note.
  </Step>

  <Step title="Retrieve results and download reports">
    Read the evaluation JSON to check progress and select the evaluation you need.
    Download a credential report as PDF or XLSX once that evaluation is completed.
    Combined reports have a separate readiness check.
  </Step>
</Steps>

For the UI steps, see [Evaluation in TruEnroll](/wiki/truenroll/evaluation).

## Credentials and targets

A case can contain several credentials, and each credential can have several evaluations.
The general evaluation has `targetInstitute: null`. When target institutes are configured,
additional evaluations identify their institute by `id` and `name`.

Select evaluations by their target or `evaluationId`. Array order does not identify the
general evaluation. Before evaluation is initiated, a credential can have no evaluation rows.

| Result | Scope | Selection |
| - | - | - |
| Credential report | One credential's evaluation | `evaluationId`, or `credentialId` for its general evaluation |
| Combined equivalency (JSON) | The case's credentials evaluated together for a selected target | `targetInstituteId`, or omit it for the general result |
| Combined report | The case's evaluated credentials for a selected target | `targetInstituteId`, or omit it for the general report |

## Evaluated output

The evaluation JSON is self-contained. It includes candidate, institution, and
qualification details alongside each credential's evaluations.

| Output | What you receive |
| - | - |
| Qualification equivalency | US equivalency, explanatory statement, normalized field of study, and evaluated qualification description |
| GPA | Weighted and unweighted GPA, each nullable |
| Credits | Computed equivalent credits, expressed as Carnegie Units for secondary and higher-secondary credentials, or Semester Credits otherwise |
| Courses | Course identifiers and names, evaluated grades, grade points, equivalent credits, and retaken, ungradable, and exclusion flags |
| Report context | Latest completion timestamp, evaluator note, and organization-specific disclaimer where available |

Evaluated course values can differ from the transcript's original values. Use
[extraction results](/partner-api/extraction) when you need the source grades, marks, and
credits. Evaluation JSON does not include grading scales or accreditation findings.

Combined equivalency, where the case's credentials are evaluated together against one target
rather than each on its own, has its own endpoint. It returns the combined statements with the
credentials they were derived from, and omits courses.

## Progress and completion

| Evaluation status | Meaning |
| - | - |
| `queued` | The evaluation has not been initiated |
| `processing` | Operator work is still in progress |
| `completed` | Evaluated output is available |
| `not_applicable` | Case-level only: nothing on the case can be evaluated (no credentials, or only uncategorized ones) |

Unfinished evaluation rows contain identifiers, status, target, and `completedAt: null`.
They omit equivalency, courses, and note. If an operator reopens an evaluation or edits a
document, completed output can return to `processing` until evaluation is completed again.

The evaluation response aggregates the credentials that can be evaluated (past extraction and
not uncategorized), the same ones `case.evaluation.completed` waits for. It is `queued` while
none of them has been evaluated, `completed` once every one has a completed evaluation, and
`processing` otherwise. A credential with no evaluation rows
counts as still waiting, so a case never reads `completed` while a credential on it is
unevaluated. Check the rows you need before requesting a report.

Case and upload status describe document processing. A completed upload does not mean
evaluation is complete. There is no evaluation `failed` status or `case.evaluation.failed`
event; an evaluation that cannot be completed remains in progress.

## Completion notifications and downloads

`case.evaluation.completed` is a case-level notification emitted when all required
evaluations are completed. It carries credential and evaluation IDs, with no `uploadId`.
It can fire again when the case is completed after an edit or reopened evaluation.

This notification is best-effort. Use it as a prompt to fetch current results, and poll
`GET /partner/v1/cases/{id}/evaluation` as a fallback. Deduplicate notifications by event
name, case ID, and completion timestamp.

A completed credential evaluation does not guarantee combined readiness. The two are tracked
separately, so every credential can be `completed` while combined equivalency for a target is
still `processing`. Combined equivalency can also be `failed`; downloading the combined report
retries it.

Poll `GET /cases/{id}/evaluation/combined` to find out when it is ready. It answers `200` with a
status instead of the `409` the report endpoints return, and reading it has no side effects.
Downloading a combined PDF does: each download generates a fresh report ID and QR verification
link.

<CardGroup cols={2}>
  <Card title="Evaluation API guide" icon="file-lines" href="/partner-api/evaluation-results">
    Endpoint paths, query selectors, response fields, and download examples.
  </Card>

  <Card title="Combined equivalency" icon="layer-group" href="/partner-api/evaluation-results#get-combined-equivalency-as-json">
    The case's credentials evaluated together, as JSON.
  </Card>

  <Card title="Completion webhooks" icon="bell" href="/partner-api/webhooks">
    Evaluation event payload, repeat completions, and delivery behavior.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.