Complete an assessment

Use an Assessment when you need to evaluate one worker’s context and supporting Documents together. Unlike a standalone Document check, an Assessment determines which evidence applies to this worker and produces a Decision across the complete case.

By the end of this guide, your backend will create a worker case, respond to requests for missing context, collect the evidence that applies, wait for evaluation, and interpret the immutable Decision.

How the workflow works

An Assessment is iterative rather than a single request-and-response operation:

1. Create the Assessment with the worker identity and context you already know.
2. Read input_requests and provide any additional context Dockt needs.
3. Read requirements and ask the user for the evidence that applies to this case.
4. Upload each evidence Document and wait for processing.
5. Read the latest Decision and route the case according to its result and Findings.

Updating context or evidence later may create a new Decision. The Assessment remains the current case, while each Decision preserves one evaluated version.

Prerequisites

You need a workspace credential with these permissions:

• features:read
• assessments:read
• assessments:write
• documents:read
• documents:create
• decisions:read

Export the API base URL and bearer token:

export DOCKT_API_BASE_URL='https://api.dockt.com'
export DOCKT_API_TOKEN='REPLACE_WITH_BEARER_TOKEN'

Your Workspace must have the intended social compliance package enabled in Features. Packages determine the possible requirements Dockt evaluates. Confirm the current configuration:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  "$DOCKT_API_BASE_URL/v1/features" | jq '.data.social_compliance_packages'

If the list doesn’t contain the package your workflow needs, configure Workspace Features before creating the Assessment. You don’t send package codes in the Assessment request; Dockt applies the active Workspace configuration automatically.

1. Create an Assessment

Create one Assessment for one worker case. Keep identity fields in worker and employment, assignment, employer, project, and evaluation values in context:

assessment_response="$(
  curl --fail-with-body --silent --show-error \
    -X POST "$DOCKT_API_BASE_URL/v1/assessments" \
    -H "Authorization: Bearer $DOCKT_API_TOKEN" \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: assessment-worker-case-1042' \
    --data '{
      "external_id": "worker-case-1042",
      "external_profile": "site-electrician",
      "worker": {
        "first_name": "Amina",
        "last_name": "Diallo",
        "date_of_birth": "1990-05-17",
        "nationality": "FR"
      },
      "context": [
        { "code": "employment.relationship", "value": "posted_employee" },
        { "code": "worker.origin", "value": "eea_swiss" },
        { "code": "employment.posting_status", "value": "posted" },
        { "code": "employment.employer_country", "value": "FR" },
        { "code": "employment.social_security_regime", "value": "eu_eea_swiss_coordination" },
        { "code": "assignment.duration_days", "value": 30 },
        { "code": "assessment.evaluation_date", "value": "2026-08-06" }
      ]
    }'
)"

export DOCKT_ASSESSMENT_ID="$(printf '%s' "$assessment_response" | jq -r '.data.id')"
printf '%s' "$assessment_response" | jq '.data | {
  id,
  status,
  input_requests,
  requirements,
  advisories
}'

external_id connects the Assessment to a stable case ID in your system. external_profile is optional and should only be sent when your Workspace has a matching profile configured.

Use context values that describe the real case. The example values illustrate the request shape; they don’t apply to every worker or package. Your create response is the first source of truth for what this Assessment needs next.

The Create assessment response shows every returned field. At this stage, latest_decision is null when Dockt still needs context or has not evaluated the current inputs.

2. Satisfy input requests

Read input_requests before uploading evidence. These are questions Dockt must answer before it can determine the applicable requirements. Each item tells you which context code is missing, why it is needed, its value_type, and any accepted options.

If requests remain, collect those values and update the Assessment:

curl --fail-with-body --silent --show-error \
  -X PATCH "$DOCKT_API_BASE_URL/v1/assessments/$DOCKT_ASSESSMENT_ID" \
  -H "Authorization: Bearer $DOCKT_API_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{
    "context": [
      { "code": "CODE_FROM_INPUT_REQUEST", "value": "VALID_VALUE" }
    ]
  }' | jq '.data.input_requests'

Replace both placeholders from the response; don’t invent context codes or values. Context values merge by code, so the update keeps other context already stored on the Assessment.

Repeat this step until input_requests is empty. While requests remain, latest_decision is null: that means more context is needed, not that the Assessment failed.

3. Review required evidence

Once context is complete, use requirements to decide which evidence to request from the user. Each requirement includes:

• required and status.
• A human-readable label and optional reason.
• accepted_evidence_types.
• Document IDs grouped by supporting, pending, review, or invalid status.

Focus on requirements where required is true and status is missing. Show the returned label and reason to explain the request to the user. Treat accepted_evidence_types as machine-readable evidence-purpose codes, not Document classification codes.

You don’t assign an upload to a requirement. After processing, the grouped Document IDs show whether a Document is still processing, supports the requirement, needs review, or is invalid. Document uploads and evidence explains the relationship between classifications and evidence types.

Don’t use a package catalog’s possible evidence list as the worker’s checklist. The Assessment response is the source for this worker’s evaluated requirements.

4. Upload an evidence document

Upload each PDF or image separately with a stable idempotency key:

document_response="$(
  curl --fail-with-body --silent --show-error \
    -X POST "$DOCKT_API_BASE_URL/v1/assessments/$DOCKT_ASSESSMENT_ID/documents" \
    -H "Authorization: Bearer $DOCKT_API_TOKEN" \
    -H 'Idempotency-Key: assessment-worker-case-1042-passport' \
    -F 'file=@./passport.pdf;type=application/pdf'
)"

export DOCKT_DOCUMENT_ID="$(printf '%s' "$document_response" | jq -r '.data.id')"
printf '%s' "$document_response" | jq '.data | {id, status, filename}'

The 202 Accepted response means Dockt accepted the upload. It doesn’t mean the Document or Assessment is complete.

Repeat this step for each relevant piece of evidence. Use a different idempotency key for each logical upload, and store the returned Document ID with the evidence record in your system.

Dockt determines how a processed Document contributes to the Assessment. Your upload request only supplies the file; don’t try to assign it to a requirement using fields that aren’t in the contract.

5. Wait for processing

Use the assessment.completed webhook in production. During development, poll the Assessment until a current Decision is available:

while true; do
  assessment_response="$(
    curl --fail-with-body --silent --show-error \
      -H "Authorization: Bearer $DOCKT_API_TOKEN" \
      "$DOCKT_API_BASE_URL/v1/assessments/$DOCKT_ASSESSMENT_ID"
  )"

  assessment_status="$(printf '%s' "$assessment_response" | jq -r '.data.status')"
  decision_id="$(printf '%s' "$assessment_response" | jq -r '.data.latest_decision.decision_id // empty')"
  printf 'Assessment status: %s\n' "$assessment_status"

  if [ -n "$decision_id" ]; then
    export DOCKT_DECISION_ID="$decision_id"
    break
  fi

  if [ "$(printf '%s' "$assessment_response" | jq '.data.input_requests | length')" -gt 0 ]; then
    printf 'Assessment needs more context.\n' >&2
    exit 1
  fi

  sleep 5
done

Dockt can create a Decision from zero or partial evidence when no linked Document is still processing. That Decision may be incomplete; it still gives you a structured explanation of what is missing. A later upload or input update can produce a newer immutable Decision.

An assessment.completed event means a Decision was produced for the current input version. It doesn’t prevent the Assessment from changing and producing another Decision later.

Stop foreground polling when your application’s waiting deadline expires. Keep the Assessment unresolved and reconcile it later; elapsed time does not imply incomplete, review_required, or non_compliant.

6. Read the complete Decision

Fetch the Decision referenced by the Assessment:

decision_response="$(
  curl --fail-with-body --silent --show-error \
    -H "Authorization: Bearer $DOCKT_API_TOKEN" \
    "$DOCKT_API_BASE_URL/v1/decisions/$DOCKT_DECISION_ID"
)"

printf '%s' "$decision_response" | jq '.data | {
  id,
  assessment_input_version,
  decision,
  signal,
  explanation,
  findings,
  requirements,
  documents
}'

Handle all four Decision values in your product:

• compliant: Continue according to your product policy.
• incomplete: Ask for the missing context or evidence identified by the response.
• review_required: Route the case to a person with its Findings and evidence links.
• non_compliant: Stop or escalate according to your product policy and show the Findings.

Start with decision, then read requirements and findings to understand why. Use Finding code and impact for routing and program logic. Use the title and explanation for reviewer-facing text. Use the display-oriented signal for presentation only.

The Get decision response shows the complete immutable shape, including Facts, source lineage, Document results, applied package versions, and optional recommendation.

The Decision is Dockt’s evaluation, not the record of what your business eventually did. Keep your acceptance, rejection, follow-up, or manual-review action separate and optionally report it as a Decision Outcome.

7. Keep Decision lineage

Store the Assessment ID, Decision ID, and assessment_input_version you acted on. Before applying a delayed action, read the Assessment again and decide whether your workflow must use its newer latest_decision.

Optionally report the downstream Outcome after your team or product acts on the Decision.