Assessments
An Assessment is the complete verification case for one worker. It brings together who the worker is, the circumstances you are evaluating, the evidence you upload, and the Workspace configuration that determines which requirements apply.
Create one Assessment for one case in your system. Use its external_id to link it to your own worker, onboarding, assignment, or access record. As the case changes, update the existing Assessment instead of creating a replacement for every new document.
The Assessment is a live resource: you can add information and evidence over time. Its Decisions are permanent snapshots of what Dockt concluded from each version of that information.
Assessment inputs
Section titled “Assessment inputs”Create an Assessment with the information your product already knows:
worker: the worker’s legal first name, last name, date of birth, and two-letter nationality code.context: coded employment, assignment, employer, project, or evaluation values.external_id: an optional identifier from your system.external_profile: an optional profile label configured for your Workspace.
The worker object answers “who is being assessed?” The context array answers “under which circumstances?” Context uses coded values so the applicable requirements can be evaluated consistently.
You don’t need to guess every possible context field before creating the Assessment. If more information is needed, Dockt returns input_requests. Each request contains the exact code, value type, reason, and allowed options when applicable. Present those requests in your own workflow, collect the values, and update the Assessment. While input requests remain, latest_decision is null because Dockt doesn’t yet have enough context to evaluate the case.
Update context with PATCH /v1/assessments/{assessmentId}. Context values merge by code, so send the codes you want to add or replace.
Assessment lifecycle
Section titled “Assessment lifecycle”Assessment status tells you what Dockt is currently doing. It is not the compliance result.
An Assessment has one of these statuses:
created: The Assessment exists and can accept input or evidence.documents_pending: One or more linked Documents haven’t finished processing.processing: Dockt is evaluating the current inputs.assessed: A current Decision is available.
After assessed, read latest_decision.decision for the semantic result. An assessed case can still be incomplete, review_required, or non_compliant; assessed only means a Decision was produced.
Evidence and evaluation
Section titled “Evidence and evaluation”The Assessment’s requirements tell you which evidence applies to this worker. Request evidence from the user based on that list, then upload each PDF or image to POST /v1/assessments/{assessmentId}/documents. Each upload creates a normal Document and links it to the Assessment.
The Document is processed first. Its result then contributes to the Assessment requirement it supports. This is why you may briefly see a Document in processing while the Assessment is documents_pending.
Dockt evaluates the current Assessment whenever no accepted linked Document is still processing. This means an Assessment can receive an incomplete, review_required, or non_compliant Decision with no or partial evidence.
A later upload, withdrawn Document, worker update, context update, or Features change can produce a newer Decision. Earlier Decisions remain unchanged, so you can always identify exactly which result your product acted on.
Inputs, requirements, and Findings
Section titled “Inputs, requirements, and Findings”These three collections answer different questions:
input_requests: What additional facts must your product collect before Dockt can evaluate the case?requirements: Which evidence applies, and has acceptable evidence satisfied it?reviewand Decisionfindings: Why does the current result need attention, and what should a reviewer inspect?
Check them in that order. First collect requested context, then collect required evidence, then interpret the Decision and its Findings.
Assessment reads
Section titled “Assessment reads”The Assessment detail response is the current working view of the case:
input_requestsfor missing context.requirementsand their evidence status.advisoriesfor external or planning obligations.documentsas linked Document summaries.reviewwith machine-readable reason codes.latest_decisionwith the current result and Findings.
The compact latest_decision is useful for a list or status screen. Follow latest_decision.decision_id with GET /v1/decisions/{decisionId} when your workflow acts on the result or a reviewer needs the complete immutable record, resolved public Facts, evidence lineage, and Document results.