Submission checks

Check uploaded work before you accept it: right brief, every question answered, word count, name and your own questions.

Price1 credit (10p) per request
Typical time5 s to 2 min
Scopemarking:write
Runs asA background job

Try it

Run submission checks in the sandbox

No key and nothing to pay. The sandbox returns a realistic example in a couple of seconds; no AI runs and no data is kept.

Request body

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Send the files a learner is about to hand in, the brief and the checks to run. Each check comes back pass, fail or unavailable with a plain explanation you can show the learner. Scans, photos and handwriting are read as images. Checks are evidence for a person, never a mark, and nothing is stored in your LMS. All checks in one request cost one charge.

Requires marking:write. Costs 1 credit per request. Send a unique Idempotency-Key; reuse it with the identical body when retrying. Returns 202 with a job: poll GET /jobs/{job_id}, stream GET /jobs/{job_id}/events, or use a signed webhook.

Submission checks

POST/v1/checks/submissions

Scope marking:write

Headers

Submission checks: headers
Field	Details
`Idempotency-Key`	stringRequiredA unique key per new operation; reuse it with the identical body when retrying.
`EduMark-Version`	enumAPI version. Defaults to the latest.One of `2026-10-21`

Request body

Submission checks: request body
Field	Details
`files`	array of FileReference or DocumentInputRequiredThe uploaded work: PDF, DOCX or TXT (inline or uploaded), or PNG, JPEG or WEBP photos via file_id.1 to 5 items
`file_id`files[].file_id	stringRequiredThe id returned by POST /v1/files, after POST /v1/files/{id}/complete reported ready.When sending FileReferencePattern `^file_[a-f0-9]{32}$`
`filename`files[].filename	stringRequiredWhen sending DocumentInputUp to 200 characters
`base64`files[].base64	stringRequiredWhen sending DocumentInputUp to 27,962,028 characters
`mime_type`files[].mime_type	string, optionalWhen sending DocumentInputUp to 150 characters
`checks`	array of BriefMatchCheck or WordCountCheck or IdentityCheck or LanguageCheck or CustomCheckRequired1 to 10 items
`name`checks[].name	string, optionalWhen sending BriefMatchCheckUp to 80 characters
`kind`checks[].kind	"brief_match"RequiredWhen sending BriefMatchCheck
`match`checks[].match	enum`same_work`: the file is an attempt at this brief. `every_question`: it also answers every question in the brief.When sending BriefMatchCheckOne of `same_work`, `every_question`Default `"same_work"`
`name`checks[].name	string, optionalWhen sending WordCountCheckUp to 80 characters
`kind`checks[].kind	"word_count"RequiredWhen sending WordCountCheck
`min_words`checks[].min_words	integer, optionalDefaults to the brief's word_count.When sending WordCountCheck1 to 100,000
`max_words`checks[].max_words	integer, optionalDefaults to the brief's word_count.When sending WordCountCheck1 to 100,000
`tolerance_percent`checks[].tolerance_percent	integerWhen sending WordCountCheck0 to 50Default `0`
`exclude_references`checks[].exclude_references	booleanWhen sending WordCountCheckDefault `true`
`name`checks[].name	string, optionalWhen sending IdentityCheckUp to 80 characters
`kind`checks[].kind	"learner_identity"RequiredWhen sending IdentityCheck
`name`checks[].name	string, optionalWhen sending LanguageCheckUp to 80 characters
`kind`checks[].kind	"language"RequiredWhen sending LanguageCheck
`language`checks[].language	stringWhen sending LanguageCheckUp to 40 charactersDefault `"English"`
`name`checks[].name	string, optionalWhen sending CustomCheckUp to 80 characters
`kind`checks[].kind	"custom"RequiredWhen sending CustomCheck
`id`checks[].id	stringRequiredWhen sending CustomCheckPattern `^[A-Za-z0-9_-]{1,64}$`
`prompt`checks[].prompt	stringRequiredA question about the work, for example “Is there a signed declaration?”When sending CustomCheckUp to 2,000 characters
`output`checks[].output	enumRequiredWhen sending CustomCheckOne of `yes_no`, `number`, `choice`, `text`
`pass_when`checks[].pass_when	enumWhen sending CustomCheckOne of `yes`, `no`Default `"yes"`
`pass_min`checks[].pass_min	number, optionalWhen sending CustomCheck-1,000,000 to 1,000,000
`pass_max`checks[].pass_max	number, optionalWhen sending CustomCheck-1,000,000 to 1,000,000
`choices`checks[].choices	array of stringWhen sending CustomCheckUp to 10 items
`pass_choices`checks[].pass_choices	array of stringWhen sending CustomCheckUp to 10 items
`brief`	Brief, optionalThe assignment the work should answer. Needed for brief_match.
`title`brief.title	stringRequiredUp to 200 characters
`instructions`brief.instructions	string, optionalUp to 3,000 characters
`questions`brief.questions	array of BriefQuestionUp to 60 items
`ref`brief.questions[].ref	stringRequiredHow the brief labels it, for example `1a` or `Task 2`.Up to 80 characters
`prompt`brief.questions[].prompt	stringRequiredUp to 1,500 characters
`word_count`brief.word_count	WordLimits, optional
`minimum`brief.word_count.minimum	integer, optional1 to 100,000
`maximum`brief.word_count.maximum	integer, optional1 to 100,000
`learner_name`	string, optionalNeeded for learner_identity.Up to 200 characters

Responses

Status	Meaning
202	Successful Response
400	Request rejected. Inspect error.code and request_id; failed work is not billed.
401	Request rejected. Inspect error.code and request_id; failed work is not billed.
402	Request rejected. Inspect error.code and request_id; failed work is not billed.
403	Request rejected. Inspect error.code and request_id; failed work is not billed.
404	Request rejected. Inspect error.code and request_id; failed work is not billed.
409	Request rejected. Inspect error.code and request_id; failed work is not billed.
410	Request rejected. Inspect error.code and request_id; failed work is not billed.
413	Request rejected. Inspect error.code and request_id; failed work is not billed.
415	Request rejected. Inspect error.code and request_id; failed work is not billed.
422	Validation Error
429	Request rejected. Inspect error.code and request_id; failed work is not billed.
503	Request rejected. Inspect error.code and request_id; failed work is not billed.

Request

curl -X POST 'https://api.edumark.ai/v1/checks/submissions' \
  -H "Authorization: Bearer $EDUMARK_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "files": [
    {
      "file_id": "file_3f2a9c0b5d7e4a1b8c6d2e0f9a8b7c6d"
    }
  ],
  "brief": {
    "title": "Improving staff retention",
    "instructions": "Write a report on staff retention at your organisation.",
    "questions": [
      {
        "ref": "1",
        "prompt": "Analyse why staff leave."
      },
      {
        "ref": "2",
        "prompt": "Propose an action plan."
      }
    ],
    "word_count": {
      "minimum": 1800,
      "maximum": 2500
    }
  },
  "learner_name": "Amelia Johnson",
  "checks": [
    {
      "kind": "brief_match",
      "match": "every_question"
    },
    {
      "kind": "word_count",
      "tolerance_percent": 10
    },
    {
      "kind": "learner_identity"
    },
    {
      "kind": "custom",
      "id": "declaration",
      "name": "Signed declaration",
      "prompt": "Is there a signed declaration of own work?",
      "output": "yes_no"
    }
  ]
}'

# Then poll until the job finishes (wait poll_after_seconds between calls)
curl 'https://api.edumark.ai/v1/jobs/job_01JB7Q8M4X2V9R' \
  -H "Authorization: Bearer $EDUMARK_API_KEY"

Queued202 and a job id, straight away
ProcessingPoll, stream or wait for a webhook
SucceededResult and files on the job

Every AI request runs as a background job, so nothing times out.

Response 202JSON

{
  "id": "job_0123456789abcdef0123456789abcdef01234567",
  "product": "submission_checks",
  "status": "queued",
  "poll_after_seconds": 2,
  "credits": 1,
  "result_available": false
}

Finished job: resultJSON

{
  "status": "completed",
  "requires_review": true,
  "checks": [
    {
      "check_id": "brief_match",
      "kind": "brief_match",
      "name": "Matches the brief",
      "status": "fail",
      "value": {
        "for_this_assignment": "yes",
        "problem": "incomplete",
        "appears_to_be": "A report on staff retention",
        "questions": [
          {
            "ref": "1",
            "attempted": "yes"
          },
          {
            "ref": "2",
            "attempted": "no"
          }
        ]
      },
      "explanation": "We couldn’t find an answer to 2 in your work. Your report covers retention well; check you’ve included the action plan.",
      "note": "",
      "details": {
        "missing": [
          "2"
        ],
        "partly": []
      }
    },
    {
      "check_id": "word_count",
      "kind": "word_count",
      "name": "Word count",
      "status": "pass",
      "value": {
        "words": 2140,
        "minimum": 1800,
        "maximum": 2500,
        "tolerance_percent": 10,
        "lowest_allowed": 1620,
        "highest_allowed": 2750
      },
      "explanation": "Your work has about 2,140 words (not counting references), which is within the word limit.",
      "note": "",
      "details": {}
    },
    {
      "check_id": "learner_identity",
      "kind": "learner_identity",
      "name": "Learner’s name on the work",
      "status": "pass",
      "value": {
        "names_on_work": [
          "Amelia Johnson"
        ],
        "belongs_to_learner": "yes"
      },
      "explanation": "The cover sheet names Amelia Johnson.",
      "note": "",
      "details": {}
    },
    {
      "check_id": "declaration",
      "kind": "custom",
      "name": "Signed declaration",
      "status": "pass",
      "value": "yes",
      "explanation": "The second page has a signed and dated declaration.",
      "note": "",
      "details": {}
    }
  ],
  "summary": {
    "pass": 3,
    "fail": 1,
    "unavailable": 0
  },
  "files": [
    {
      "filename": "report.pdf",
      "readable": true,
      "words": 2310,
      "read_from_images": []
    }
  ],
  "provenance": {
    "engine": "journey_submission_checks",
    "sandbox": true
  }
}