Complete an assessment

Dockt checks a worker’s documents and details against the requirements configured for your workflow. Each worker case is called an Assessment. Dockt works out which evidence is needed, checks the available information, and saves the result as a Decision.

This guide takes you from creating a case to using its result in your application. You can start with the details you know and add more information or documents later.

How the workflow works

An Assessment can change as information arrives. Your backend follows these steps:

1. Create the Assessment with the worker and assignment details you already know.
2. Upload the files the user has and wait for processing.
3. Show the saved result, called a Decision, and its explanations, called Findings. Use requirements to show missing or incorrect evidence. If Dockt has too little information to check the worker, explain that in one short summary.
4. If your system knows details listed in input_requests, send those values to Dockt. Don’t ask users to complete a questionnaire.
5. Add documents or update details as the case changes.

Updating details or evidence later may create a new Decision. The Assessment holds the current case, while each Decision preserves the result of one evaluation.

Prerequisites

You need a workspace credential with these permissions:

• workspace-configuration:read
• assessments:read
• assessments:write
• documents:read
• documents:create
• decisions:read
• social-compliance-packages: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 groups your cases and their configuration. Its active Assessment Policy must include the social compliance package you want to use. A package supplies the checks for a supported country and type of work. Confirm the selected packages:

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

If the list doesn’t contain the package your workflow needs, follow Configure Assessment and Monitoring Policy before you continue. You don’t send package codes in the Assessment request.

1. Create an Assessment

Create one Assessment for one worker case. Send the details you know in inputs, and identify where each value came from with source. You can send some details or create an empty case. This example includes identity and assignment details:

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",
      "job": {
        "namespace": "contract_management",
        "external_id": "site-electrician"
      },
      "inputs": [
        {
          "code": "person.name.first",
          "value": "Amina",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "person.name.last",
          "value": "Diallo",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "person.date_of_birth",
          "value": "1990-05-17",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "person.nationality",
          "value": "FR",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "employment.relationship",
          "value": "employee",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "employment.posting_status",
          "value": "posted",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "employment.employer_country",
          "value": "FR",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "employment.social_security_regime",
          "value": "eu_eea_swiss_coordination",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "assignment.duration_days",
          "value": 30,
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        },
        {
          "code": "assessment.evaluation_date",
          "value": "2026-08-06",
          "source": {
            "kind": "integration",
            "reference": "contract_management:worker:1042"
          }
        }
      ]
    }'
)"

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. The optional job reference selects the active Job Profile mapped to that namespace and external identifier. A Job Profile defines qualification requirements for a job.

To try the request without your own credential, run this fictional worker case in Dockt’s temporary shared Workspace. Open the result in the Workbench, an interactive API testing tool, to add documents and read the Decision:

For your own integration, use values that describe the actual case. The example values show the request format; they don’t apply to every worker or package. Read the create response to see what this Assessment needs next.

The Create assessment response describes every returned field. latest_decision is null until a current Decision is available. Missing details can result in an incomplete Decision with unresolved input_requests.

2. Supply known context

This step is optional when your system has no more details to supply. You can continue to Upload an evidence document while details are still missing.

Read input_requests with the results. Each entry describes a detail a check still needs, the reason, its value_type, and any accepted options. Dockt continues any checks that have enough information.

If your system already knows those values, 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 '{
    "inputs": [
      { "code": "CODE_FROM_INPUT_REQUEST", "value": "VALID_VALUE", "source": { "kind": "integration", "reference": "your_system:assignment:1042" } }
    ]
  }' | jq '.data.input_requests'

Replace CODE_FROM_INPUT_REQUEST with a returned field code and VALID_VALUE with a known value of the requested type. Keep source.reference stable for the record that supplies the value. Don’t guess missing values or ask users to fill them in.

A correction replaces the current value for the same code and source. Dockt keeps the history, other sources, and earlier Decisions.

Repeat this step as you obtain the requested details. While requests remain, Dockt can finish evaluating the available evidence and produce an incomplete Decision. Read those input requests even when latest_decision is present.

3. Review required evidence

After Dockt checks the available files, use requirements to show missing or incorrect evidence for this worker. Evidence means documents or other information that support a check. 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. accepted_evidence_types lists codes for the evidence a requirement accepts. These can differ from the type Dockt assigns to an uploaded Document.

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.

Build the worker’s checklist from the Assessment response. A package catalog lists possible evidence across many cases, including requirements that might not apply to this worker.

A missing status can mean evidence is absent, invalid, or ambiguous. When a Decision is available, read decision and each Finding’s impact to distinguish these cases.

For qualification requirements, use the returned label, reason, and supporting_document_ids even if accepted_evidence_types is empty. If policy requires uploaded proof, the document must support the qualification being accepted. See Uploaded qualification proof.

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 which requirements a processed Document supports. Your upload request supplies only the file.

5. Wait for processing

In production, configure a Notification Destination to receive assessment.completed when Dockt produces a Decision. 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

  sleep 5
done

When no linked Document is still processing, Dockt can create a Decision even if evidence is missing. That Decision may be incomplete; it explains what is still needed. A later upload or input update can produce a newer Decision without changing the earlier result.

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 polling when your application’s waiting deadline expires. Keep the case unresolved and read it again later. A timeout doesn’t 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: Show the missing evidence identified by the response. If Dockt has too little information to check the worker, show one short summary. Let users add documents, and supply details your system already knows.
• 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 the result. Use each Finding’s code and impact in application logic. Show its title and explanation to the reviewer. Use signal only to display the result.

The Get decision response describes the full saved record: the values Dockt evaluated, their sources, Document results, package versions, and optional recommendation.

The Decision records Dockt’s evaluation. Your business decides whether to accept, reject, follow up, or review the case. Keep that action in a separate record. You can also report it to Dockt as a Decision Outcome.

7. Keep Decision lineage

Store the Assessment ID, Decision ID, and assessment_input_version you acted on so you can trace the action to its result. 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.