Create assessment

POST

/v1/assessments

const url = 'https://api.dockt.com/v1/assessments';
const options = {
  method: 'POST',
  headers: {
    'x-dockt-expected-workspace': 'wsp_example',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"external_id":"worker-case-1042","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"}}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api.dockt.com/v1/assessments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-dockt-expected-workspace: wsp_example' \
  --data '{ "external_id": "worker-case-1042", "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" } } ] }'

Creates a verification case for one worker in the active workspace and returns required evidence based on the effective workspace policy. Requires assessments:write, decisions:read, documents:read, and social-compliance-packages:read, including when reuse_existing returns an existing case.

Authorizations

bearerAuth
sessionCookie

Parameters

Header Parameters

x-dockt-expected-user

Rejects the request with 401 unless the browser session belongs to this auth_user_id. This assertion does not grant authority.

string

>= 1 characters

x-dockt-expected-workspace

Unique Dockt workspace identifier.

idempotency-key

Caller-generated retry key for duplicate-sensitive create and resend operations. Keys are scoped to the authenticated principal, method, and route and are retained for 24 hours.

string

>= 1 characters

Request Body^required

application/json

Creates a case for one worker in the active workspace. You can start with no details and add inputs and documents later. Dockt uses the workspace selected by your authentication and its configured policy to determine the evidence requirements for the worker.

object

external_id

string

reuse_existing

Atomically returns the existing assessment with this external_id in the active workspace, or creates one if absent. Requires a nonblank external_id; multiple matches return 409. Existing inputs are not updated. Omit to create a new case even when the external_id is already used.

boolean

job

Namespaced customer job identifier resolved through the active Job Profile revisions.

object

namespace

required

string

>= 1 characters

external_id

required

string

>= 1 characters

inputs

Array<object>

<= 64 items

A value you provide with its source, called a Claim. Send null to withdraw the current value from that source. Dockt determines whether evidence verifies the value; your application cannot set verification.

object

code

required

string

>= 1 characters

value

required

Any of:

unknown
null

Any of:

string

source

required

object

kind

required

string

Allowed values: integration operator

reference

required

string

>= 1 characters <= 240 characters

valid_from

ISO 8601 calendar date string.

string format: date

valid_until

ISO 8601 calendar date string.

string format: date

reconciliation

object

claim_ids

required

Array<string>

>= 1 items

reason

required

string

>= 1 characters <= 2000 characters

Example

{
  "external_id": "worker-case-1042",
  "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"
      }
    }
  ]
}

Responses

201

Envelope for a single resource response.

application/json

Envelope for a single resource response.

object

object

required

string

Allowed values: single

data

required

A case containing one worker’s details, documents, and evaluation results in a Workspace. The Workspace configuration determines which requirements apply.

object

object

required

string

Allowed values: assessment

required

Unique Dockt assessment identifier.

string

workspace_id

required

Unique Dockt workspace identifier.

string

external_id

required

Any of:

string
null

string

job

required

Any of:

object
null

Namespaced customer job identifier resolved through the active Job Profile revisions.

object

namespace

required

string

>= 1 characters

external_id

required

string

>= 1 characters

resolved_job_profile_id

required

Any of:

string
null

string

status

required

Lifecycle state for an assessment.

string

Allowed values: created documents_pending processing assessed

worker

required

Any of:

object
null

Read-only summary of the worker identity Dockt can establish from the available information. All known nationalities are kept. Fields that remain unknown or conflicting are omitted.

object

name

string

>= 1 characters

nationalities

Array<string>

first_name

string

>= 1 characters

last_name

string

>= 1 characters

date_of_birth

ISO 8601 calendar date string.

string format: date

inputs

required

Array<object>

object

code

required

string

>= 1 characters

value

required

Any of:

unknown
null

Any of:

string

source

required

object

kind

required

string

Allowed values: integration operator

reference

required

string

>= 1 characters <= 240 characters

valid_from

ISO 8601 calendar date string.

string format: date

valid_until

ISO 8601 calendar date string.

string format: date

reconciliation

object

claim_ids

required

Array<string>

>= 1 items

reason

required

string

>= 1 characters <= 2000 characters

required

string

normalized_value

required

Any of:

unknown
null

Any of:

string

subject

required

string

recorded_at

required

ISO 8601 date-time string.

string format: date-time

superseded_by

required

Any of:

string
null

string

resolved_inputs

required

Array<object>

The value Dockt can use for a field, its sources, and how it is supported or verified. The status identifies values that are established, unknown, or conflicting.

object

code

required

string

label

required

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

subject

required

string

status

required

string

Allowed values: established insufficient_information conflicting_information

value

required

Any of:

unknown
null

Any of:

string

assurance

required

Known values: declared, document_supported, authority_verified. New values may appear; preserve unfamiliar values and use a safe fallback.

string

>= 1 characters

reconciliation

object

claim_ids

required

Array<string>

reason

required

string

sources

required

Array<object>

object

claim_id

required

string

kind

required

string

reference

required

string

document_id

required

Any of:

string
null

Unique Dockt document identifier.

string

observed_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

fresh_until

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

value

required

Any of:

string

normalized_value

required

Any of:

string

input_requests

required

Array<object>

A question about details still needed to evaluate the requirements in your active policy. An incomplete Decision may be available while questions remain unanswered.

object

code

required

string

>= 1 characters

label

required

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

value_type

required

Known values: string, integer, boolean, date, country_code, single_select. New values may appear; preserve unfamiliar values and use a safe fallback.

string

>= 1 characters

cardinality

Known values: one, many. New values may appear; preserve unfamiliar values and use a safe fallback.

string

>= 1 characters

max_items

integer

>= 1 <= 8

unit

string

>= 1 characters

options

required

Array<object>

object

value

required

string

>= 1 characters

label

required

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

reason

required

string

>= 1 characters

applied_packages

required

Array<object>

Exact executable compliance-package release applied to an assessment.

object

code

required

string

>= 1 characters

version

required

string

>= 1 characters

requirements

required

Array<object>

Policy-neutral evidence requirement and its current assessment status.

object

code

required

string

>= 1 characters

label

required

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

reason

required

Any of:

string
null

string

>= 1 characters

status

required

Current result of evaluating one evidence requirement.

string

Allowed values: missing not_required satisfied

required

required

boolean

source_domain

required

string

>= 1 characters

package

required

Any of:

object
null

Exact executable compliance-package release applied to an assessment.

object

code

required

string

>= 1 characters

version

required

string

>= 1 characters

accepted_evidence_types

required

Array<string>

supporting_document_ids

required

Array<string>

pending_document_ids

required

Array<string>

review_document_ids

required

Array<string>

invalid_document_ids

required

Array<string>

advisories

required

Array<object>

External or planning obligation signaled by an applied compliance package.

object

code

required

string

>= 1 characters

label

required

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

reason

required

string

>= 1 characters

severity

required

string

Allowed values: info mandatory_external review_recommended

phase

required

Any of:

string
null

string

Allowed values: pre_access pre_start during_assignment payment_time post_assignment on_request

package

required

Exact executable compliance-package release applied to an assessment.

object

code

required

string

>= 1 characters

version

required

string

>= 1 characters

documents

required

Array<object>

Assessment-embedded summary of a canonical document, plus assessment-scoped match status.

object

object

required

string

Allowed values: document

required

Unique Dockt document identifier.

string

status

required

Processing lifecycle state for a workspace document.

string

Allowed values: uploaded processing completed failed withdrawn

document_result

required

Any of:

string
null

Document-intrinsic verdict produced after processing completes.

string

Allowed values: valid review_required invalid

match_status

required

Any of:

string
null

Result of deterministic document checks inside an assessment.

string

Allowed values: pending valid invalid mismatch no_profile unknown expired_no_profile

filename

required

string

>= 1 characters

classified_as

required

Any of:

object
null

Dockt document classification assigned after processing.

object

family

required

string

>= 1 characters

type

required

string

>= 1 characters

variant

required

Any of:

string
null

string

>= 1 characters

issues

required

Array<object>

Machine-readable document issue with a human-readable reason.

object

code

required

string

>= 1 characters

reason

required

string

>= 1 characters

uploaded_at

required

ISO 8601 date-time string.

string format: date-time

completed_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

review

required

Whether the assessment needs manual review and the machine-readable reasons.

object

review_required

required

boolean

reason_codes

required

Array<string>

monitoring

required

Customer-safe periodic monitoring state for an assessment.

object

enabled

required

boolean

status

required

string

Allowed values: disabled active stopped ended point_in_time

next_reassessment_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

monitoring_ends_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

last_reassessed_at

required

Any of:

string
null

ISO 8601 date-time string.

string format: date-time

latest_decision

required

Any of:

object
null

Compact current decision with actionable findings projected into an assessment detail response.

object

decision_id

required

Unique Dockt decision identifier.

string

assessment_input_version

required

integer

>= 1

decision

required

Dockt decision for an assessment based on available worker context and evidence.

string

Allowed values: incomplete compliant non_compliant review_required

signal

required

Customer-facing traffic-light signal derived from the semantic decision.

string

Allowed values: green yellow red

explanation

required

string

>= 1 characters

findings

required

Array<object>

object

required

string

>= 1 characters

code

required

string

>= 1 characters

scope

required

string

Allowed values: assessment document requirement

impact

required

string

Allowed values: informational incomplete review_required non_compliant

title

required

string

>= 1 characters

explanation

required

string

>= 1 characters

document_ids

required

Array<string>

requirement_codes

required

Array<string>

recommendation

required

Any of:

object
null

Typed review-assistance recommendation captured with a decision.

object

action

required

string

Allowed values: approve review reject request_update

confidence

required

number

<= 1

mode

required

string

Allowed values: shadow review_assist

created_at

required

ISO 8601 date-time string.

string format: date-time

created_at

required

ISO 8601 date-time string.

string format: date-time

updated_at

required

ISO 8601 date-time string.

string format: date-time

Example

{
  "object": "single",
  "data": {
    "object": "assessment",
    "id": "ast_example1042",
    "workspace_id": "wsp_example1042",
    "external_id": "worker-case-1042",
    "job": null,
    "resolved_job_profile_id": null,
    "status": "created",
    "inputs": [],
    "resolved_inputs": [],
    "worker": {
      "first_name": "Amina",
      "last_name": "Diallo",
      "date_of_birth": "1990-05-17",
      "nationalities": [
        "FR"
      ]
    },
    "input_requests": [
      {
        "code": "project.is_construction",
        "label": "Construction project",
        "reason": "The applicable requirements depend on whether the work is construction work.",
        "value_type": "boolean",
        "options": []
      }
    ],
    "applied_packages": [
      {
        "code": "social_construction_be_v1",
        "version": "v1"
      }
    ],
    "requirements": [],
    "advisories": [],
    "documents": [],
    "review": {
      "review_required": false,
      "reason_codes": []
    },
    "monitoring": {
      "enabled": false,
      "status": "disabled",
      "next_reassessment_at": null,
      "monitoring_ends_at": null,
      "last_reassessed_at": null
    },
    "latest_decision": null,
    "created_at": "2026-08-23T09:30:00Z",
    "updated_at": "2026-08-23T09:30:00Z"
  }
}

400

Problem Details response for HTTP 400. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/invalid-request",
  "title": "Bad request",
  "status": 400,
  "detail": "The request did not match the expected schema.",
  "instance": "req_example1042"
}

401

Problem Details response for HTTP 401. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/missing-auth",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Send a valid bearer token or browser session.",
  "instance": "req_example1042"
}

403

Problem Details response for HTTP 403. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "The authenticated principal does not have the required permission.",
  "instance": "req_example1042"
}

404

Problem Details response for HTTP 404. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "The requested resource was not found in the authenticated scope.",
  "instance": "req_example1042"
}

409

Problem Details response for HTTP 409. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "detail": "The request conflicts with the current resource state.",
  "instance": "req_example1042"
}

422

Problem Details response for HTTP 422. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "Correct the invalid fields and send the request again.",
  "instance": "req_example1042",
  "errors": {
    "issues": [
      {
        "path": [
          "body",
          "inputs",
          "3",
          "value"
        ],
        "message": "Expected a two-letter country code."
      }
    ]
  }
}

429

Problem Details response for HTTP 429. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/rate-limit",
  "title": "Too many requests",
  "status": 429,
  "detail": "Wait for the Retry-After interval before retrying.",
  "instance": "req_example1042"
}

500

Problem Details response for HTTP 500. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "type": "https://docs.dockt.com/errors/internal",
  "title": "Internal server error",
  "status": 500,
  "detail": "Retry the request safely or contact Dockt support with the request ID.",
  "instance": "req_example1042"
}

503

Problem Details response for HTTP 503. The type URI is the stable machine-readable error code.

application/problem+json

Standard error response with a stable status, human-readable detail, and optional validation errors.

object

type

required

string

title

required

string

status

required

number

detail

required

string

instance

required

Any of:

string
null

Request identifier that Dockt support can use to trace an API call.

string

errors

Structured request validation issues.

object

issues

required

Array<object>

One request validation issue with a stable field path and human-readable message.

object

path

required

Array

message

required

string

Example

{
  "instance": "req_example1042"
}

Create assessment

Authorizations

Parameters

Header Parameters

Request Bodyrequired

Example

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

503

Example

Analytics cookies

Request Body^required