Cases

A case represents a single candidate or evaluation subject. It is the same case an operator sees in TruEnroll, so the IDs the API returns are TruEnroll’s own and match what operators see. You identify a case with your externalId. Each time you submit documents for the same externalId, a new upload is added to the existing case. Credentials (extracted documents) accumulate across all uploads. Case and upload statuses describe document processing. They do not indicate whether an operator has completed evaluation. Use evaluation results to check evaluation progress and download reports. Evaluation is not an upload feature.

Create a case / add an upload

POST /partner/v1/cases
Content-Type: multipart/form-data

If the externalId already exists for your organization, the files are added as a new upload to the existing case. If not, a new case is created.

Request fields

file[]

required

One or more document files. Accepted formats: PDF, PNG, JPG, JPEG, WebP, ZIP. Up to 20 files per request. The API accepts up to 100 MiB per file and 100 MiB total payload. Files inside a ZIP that are not of a supported type will appear in the upload’s files[] list but will not be processed. PDFs are limited to 200 pages in production.

string

required

Your reference for this case: the candidate ID, application number, or any identifier that maps to a person in your system. Unique per organization. Subsequent submissions with the same externalId append to the existing case. At most 128 characters.

string

Link an existing TruEnroll case, created by an operator in the TruEnroll UI, to your externalId. Pass its case ID or case number. The files become a new upload on that case, and later submissions with the same externalId go to it as well. See Linking a TruEnroll case.

string (JSON array)

Which capabilities to run on this upload. Valid values: "extraction", "forensics", "translation". Defaults to all three when omitted.A feature you do not request does not run. An operator can still start it later from TruEnroll, and once it has run, its results appear in the API like any requested feature.

features=["extraction","forensics"]

boolean

default:"true"

Whether to run AI document classification. When true (default), TruEnroll analyses the uploaded files and splits them into credentials, one per education qualification identified. When false, classification is skipped and the whole upload becomes a single academic credential, which the requested features then run on. Use this only if you know the upload holds one qualification.classify: false with an empty features array returns 400, because there would be nothing to process.Either way the case appears in TruEnroll and receives a case number, so an operator can pick it up and evaluate it.

object (JSON)

Arbitrary key-value pairs attached to the case. Values must be strings, numbers, or booleans.

metadata={"applicationCycle":"2025","region":"APAC"}

Optional headers

string

Makes the upload safe to retry. If a request fails or times out, resend it with the same Idempotency-Key and an identical payload, and TruEnroll returns the original upload instead of creating a duplicate, showing that upload’s current status. Reusing a key with a different payload returns 409 Conflict.

A successful submission returns 202 Accepted. The files are accepted and processing runs asynchronously. Watch webhooks or poll GET /cases/{id} for results.

Example

curl -X POST https://api.truenroll.com/partner/v1/cases \
  -H "x-api-key: $TRUENROLL_API_KEY" \
  -F "files=@transcript.pdf" \
  -F "externalId=applicant-9876" \
  -F 'features=["extraction","forensics","translation"]'

Response fields

boolean

Always true on a successful response.

string

Human-readable confirmation, e.g. "Upload accepted".

object

Show data

string

TruEnroll’s unique ID for the case. Use this to fetch results and check status.

string

The externalId you provided at submission.

number

The case number shown in TruEnroll and printed on reports. This is the identifier people quote to each other, and it can be passed as {id} on any case route.

object

Details of the upload that was just created.

Show upload

string

Unique ID for this upload. Each POST /cases call produces a new upload.

string

Aggregate processing status for this upload. One of queued, processing, completed, failed.

boolean

Whether classification was requested for this upload.

object[]

The features enabled for this upload, each with its own status.

Show features[]

string

Feature name: extraction, forensics, or translation.

string

Per-feature status: queued, processing, completed, or failed.

object[]

The source files included in this upload.

Show files[]

string

Unique ID for this file within the upload.

string

Original filename as uploaded.

string (ISO 8601)

Timestamp when the upload was created.

string (ISO 8601)

Timestamp when the upload was last updated.

{
  "success": true,
  "message": "Upload accepted",
  "meta": {},
  "data": {
    "caseId": "6850abc123def456abc78901",
    "externalId": "applicant-9876",
    "caseNumber": 10482,
    "upload": {
      "uploadId": "6850def456abc789abc12301",
      "status": "processing",
      "classify": true,
      "features": [
        { "name": "extraction", "status": "processing" },
        { "name": "forensics", "status": "processing" },
        { "name": "translation", "status": "processing" }
      ],
      "files": [
        { "fileId": "file_abc", "fileName": "transcript.pdf" }
      ],
      "createdAt": "2025-06-22T10:00:00Z",
      "updatedAt": "2025-06-22T10:00:00Z"
    }
  }
}

Addressing a case

Every /cases/{id} route accepts either identifier:

Identifier	Looks like	Where it comes from
Case ID	`6850abc123def456abc78901`	`caseId` in the `POST /cases` response, `data.id` on any case response, or `caseId` in a webhook
Case number	`10482`	`caseNumber` on every case response, including `POST /cases`; also shown in TruEnroll and printed on reports

The two never collide: a case ID is a 24-character hexadecimal string and a case number is digits only. The case ID is TruEnroll’s own ID for the case, and uploadId, credentialId, and evaluationId are likewise TruEnroll’s own IDs. Whether a case came from POST /cases or from the TruEnroll UI, its IDs are the same in the API, in webhooks, and in TruEnroll. Case numbers are unique across all organizations, and a lookup is still scoped to yours, so a number belonging to another organization returns 404.

Cases created in the TruEnroll UI

Your key can read every active case in your organization, including cases an operator created in TruEnroll rather than through POST /cases. They appear in GET /cases and behave like any other case, with these differences:

externalId is null, until you link the case to one
a credential an operator added by hand, with no upload behind it, has uploadId: null
an upload has the features that have actually run on it. A case that was never translated does not list translation, and GET /cases/{id}/translation returns 409 for it
no webhooks are sent for the case’s processing, since you did not submit its uploads
DELETE returns 403; delete the case in TruEnroll instead

Linking a TruEnroll case

To bring a TruEnroll case into your integration, submit an upload with caseId set to its case ID or case number, and your own externalId:

curl -X POST https://api.truenroll.com/partner/v1/cases \
  -H "x-api-key: $TRUENROLL_API_KEY" \
  -F "files=@transcript.pdf" \
  -F "externalId=applicant-9876" \
  -F "caseId=10482"

From then on the externalId names that case, and later uploads to it need only the externalId. Your uploads on the case send webhooks, and case.evaluation.completed fires for it. A linked case still belongs to TruEnroll, so DELETE returns 403.

Situation	Result
`caseId` not found in your organization	`404`
The case is already linked to another `externalId`	`409` `Case is already linked to a partner`
Your `externalId` already names a different case	`409` `externalId belongs to a different case`

A matching externalId alone never links a case; only caseId does.

A case number is not a credential identifier. A case with three credentials still has one case number.

Get a case

GET /partner/v1/cases/{id}

Returns the full case including all uploads and their credentials.

Path parameters

string

required

TruEnroll case ID (caseId) returned when the case was created, or the case number. See Addressing a case.

Response fields

object

Show data

string

TruEnroll’s unique case ID.

string

Your reference for this case. null for a case created in the TruEnroll UI.

number

The case number shown in TruEnroll and printed on reports. This is the identifier people quote to each other, and it can be passed as {id} on any case route.

object

The metadata you submitted, or null. A later upload’s metadata is merged in, its keys replacing existing ones.

string

Aggregate status across all uploads and features. One of queued, processing, completed, failed. A case is completed only when every upload and every enabled feature has reached a terminal state. A later upload returns the case to processing.

object[]

All uploads on this case: one per POST /cases call, plus any an operator added in TruEnroll.

Show uploads[]

string

Unique ID for this upload.

string

Processing status: queued, processing, completed, failed.

boolean

Whether classification was run on this upload.

object[]

The features you requested for this upload, plus any an operator has since run on it, each with its own status. A multi-credential upload’s feature is completed only when it has completed on every credential.

Show features[]

string

Feature name: extraction, forensics, or translation.

string

Per-feature status: queued, processing, completed, or failed.

object[]

Source files included in this upload.

Show files[]

string

Unique file ID.

string

Original filename.

string (ISO 8601)

Upload creation timestamp.

string (ISO 8601)

Upload last-updated timestamp.

object[]

Education credentials identified by classification across all uploads. One credential is produced per education qualification found. A single file can yield multiple credentials.

Show credentials[]

string

Unique credential ID. Used to correlate extraction and forensics results.

string

ID of the upload that produced this credential. null for a credential an operator added by hand.

string

Document category assigned by classification, e.g. Academic Credentials, Healthcare & Licensure. null if classification has not completed.

string

Processing status: queued, processing, completed, failed.

string (ISO 8601)

Case creation timestamp.

string (ISO 8601)

Case last-updated timestamp.

{
  "success": true,
  "message": "Case retrieved",
  "meta": {},
  "data": {
    "id": "6850abc123def456abc78901",
    "externalId": "applicant-9876",
    "caseNumber": 10482,
    "metadata": { "applicationCycle": "2025" },
    "status": "processing",
    "createdAt": "2025-06-22T10:00:00Z",
    "updatedAt": "2025-06-22T10:05:00Z",
    "uploads": [
      {
        "uploadId": "6850def456abc789abc12301",
        "status": "completed",
        "classify": true,
        "features": [
          { "name": "extraction", "status": "completed" },
          { "name": "forensics", "status": "completed" },
          { "name": "translation", "status": "completed" }
        ],
        "files": [
          { "fileId": "file_abc", "fileName": "transcript.pdf" }
        ],
        "createdAt": "2025-06-22T10:00:00Z",
        "updatedAt": "2025-06-22T10:04:00Z"
      }
    ],
    "credentials": [
      {
        "credentialId": "6850abc789abc123def45601",
        "uploadId": "6850def456abc789abc12301",
        "credentialType": "Academic Credentials",
        "status": "completed"
      }
    ]
  }
}

List cases

GET /partner/v1/cases

Returns every active case in your organization, newest first, in the same shape as GET /cases/{id}. This includes cases created in the TruEnroll UI. Deleted cases are not listed.

Query parameters

string

Return only the case with this externalId: a one-item list, or an empty list.

number

Number of results per page. Default: 20, max: 100.

number

Number of results to skip for pagination. Default: 0.

Delete a case

DELETE /partner/v1/cases/{id}

Deletes the case, with its documents, from TruEnroll as well. It no longer appears in list results and subsequent requests return 404. A deleted case cannot receive new uploads: submitting the same externalId after deletion returns 409 Conflict. Only cases you created through POST /cases can be deleted:

Situation	Result
Case created in the TruEnroll UI	`403` `Case was not created through the Partner API`
Case you linked from TruEnroll	`403` `Case was linked from the UI; delete it there`
A document on the case is still processing	`400` `Case cannot be deleted while processing`; retry later

A case an operator deletes in TruEnroll also returns 404 from then on.

Path parameters

string

required

TruEnroll case ID, or the case number. See Addressing a case.

Returns 204 No Content on success.

Error codes

Code	Reason
`202`	Success. Upload accepted for asynchronous processing
`400`	Missing files, unsupported format, a file below the 1 KB minimum, invalid JSON, an invalid `features` value or nested `metadata` (the message names the field), `classify: false` with no features, or deleting a case that is still processing
`401`	No API key, or an invalid/expired key
`403`	Key is not a partner key, key is inactive, organization lacks a requested feature, or deleting a case created in or linked from the TruEnroll UI
`404`	Case not found or deleted, a `caseId` to link that is not in your organization, or an unknown `/partner/v1` path
`409`	Submitting to a deleted case, a case still initializing, reusing an `Idempotency-Key` with a different payload, or a linking conflict
`413`	File-count, per-file (100 MiB), or total payload (100 MiB) limit exceeded

Features & limits

Full details on upload constraints and feature capability requirements.

Overview

Guides

API Reference

Create a case / add an upload

Request fields

Optional headers

Example

Response fields

Addressing a case

Cases created in the TruEnroll UI

Linking a TruEnroll case

Get a case

Path parameters

Response fields

List cases

Query parameters

Delete a case

Path parameters

Error codes

Features & limits

​Create a case / add an upload

​Request fields

​Optional headers

​Example

​Response fields

​Addressing a case

​Cases created in the TruEnroll UI

​Linking a TruEnroll case

​Get a case

​Path parameters

​Response fields

​List cases

​Query parameters

​Delete a case

​Path parameters

​Error codes

Features & limits

Create a case / add an upload

Request fields

Optional headers

Example

Response fields

Addressing a case

Cases created in the TruEnroll UI

Linking a TruEnroll case

Get a case

Path parameters

Response fields

List cases

Query parameters

Delete a case

Path parameters

Error codes