Create assessment

POST

/v1/assessments

const url = 'https://api.dockt.com/v1/assessments';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"external_id":"worker-case-1042","worker":{"first_name":"Amina","last_name":"Diallo","date_of_birth":"1990-05-17","nationality":"FR"},"context":[{"code":"employment.relationship","value":"posted_employee"},{"code":"employment.employer_country","value":"FR"}]}'
};

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' \
  --data '{ "external_id": "worker-case-1042", "worker": { "first_name": "Amina", "last_name": "Diallo", "date_of_birth": "1990-05-17", "nationality": "FR" }, "context": [ { "code": "employment.relationship", "value": "posted_employee" }, { "code": "employment.employer_country", "value": "FR" } ] }'

Creates a verification case for one worker in the active workspace and returns required evidence based on workspace Features.

Authorizations

bearerAuth
sessionCookie

Parameters

Header Parameters

idempotency-key

minLength(1)

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

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.

Request Body^required

application/json

Creates an assessment in the active workspace. Dockt resolves workspace Features and evidence requirements from the authenticated principal and provided worker context.

object

external_id

string

external_profile

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

worker

required

Portable worker identity snapshot. Policy and assignment context is supplied separately.

object

first_name

required

minLength(1)

Worker legal first name.

string

>= 1 characters

last_name

required

minLength(1)

Worker legal last name.

string

>= 1 characters

date_of_birth

required

ISO 8601 calendar date string.

string format: date

nationality

required

maxLength(2)

Worker nationality as an ISO 3166-1 alpha-2 country code.

string

>= 2 characters <= 2 characters

context

Array<object>

Package-independent employment, assignment, employer, project, or evaluation context.

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

value

required

Any of:

string

Example

{
  "external_id": "worker-case-1042",
  "worker": {
    "first_name": "Amina",
    "last_name": "Diallo",
    "date_of_birth": "1990-05-17",
    "nationality": "FR"
  },
  "context": [
    {
      "code": "employment.relationship",
      "value": "posted_employee"
    },
    {
      "code": "employment.employer_country",
      "value": "FR"
    }
  ]
}

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

Workspace-scoped verification case for one worker. Workspace configuration selects policy; callers submit package-independent context.

object

object

required

string

Allowed values: assessment

required

Unique Dockt assessment identifier.

string

/^ast_[A-Za-z0-9_]+$/

workspace_id

required

Unique Dockt workspace identifier.

string

/^wsp_[A-Za-z0-9_]+$/

features_id

required

Unique identifier for a version of workspace Features.

string

/^feat_[A-Za-z0-9_]+$/

external_id

required

Any of:

string
null

string

external_profile

required

Any of:

string
null

string

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

Portable worker identity snapshot. Policy and assignment context is supplied separately.

object

first_name

required

minLength(1)

Worker legal first name.

string

>= 1 characters

last_name

required

minLength(1)

Worker legal last name.

string

>= 1 characters

date_of_birth

required

ISO 8601 calendar date string.

string format: date

nationality

required

maxLength(2)

Worker nationality as an ISO 3166-1 alpha-2 country code.

string

>= 2 characters <= 2 characters

context

required

Array<object>

Package-independent employment, assignment, employer, project, or evaluation context.

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

value

required

Any of:

string

input_requests

required

Array<object>

Additional package-independent context needed before a Decision can be created. While requests remain, latest_decision is null.

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

label

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

reason

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

value_type

required

string

Allowed values: string integer boolean date country_code single_select

options

required

Array<object>

object

value

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

label

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

applied_packages

required

Array<object>

Exact executable compliance-package release applied to an assessment.

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

version

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

requirements

required

Array<object>

Policy-neutral evidence requirement and its current assessment status.

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

label

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

reason

required

Any of:

minLength(1)
null

minLength(1)

A string at least 1 character(s) long

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

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

package

required

Any of:

object
null

Exact executable compliance-package release applied to an assessment.

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

version

required

minLength(1)

A string at least 1 character(s) long

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

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

label

required

maxLength(120)

Human-readable name shown in Dockt and customer systems.

string

>= 1 characters <= 120 characters

reason

required

minLength(1)

A string at least 1 character(s) long

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

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

version

required

minLength(1)

A string at least 1 character(s) long

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

/^doc_[A-Za-z0-9_]+$/

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

How a document matched deterministic worker profile checks inside an assessment.

string

Allowed values: pending valid invalid mismatch no_profile unknown expired_no_profile

filename

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

classified_as

required

Any of:

object
null

Dockt document classification assigned after processing.

object

family

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

type

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

variant

required

Any of:

minLength(1)
null

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

issues

required

Array<object>

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

object

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

reason

required

minLength(1)

A string at least 1 character(s) long

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>

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

/^dec_[A-Za-z0-9_]+$/

assessment_input_version

required

greaterThanOrEqualTo(1)

A number greater than or equal to 1

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

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

findings

required

Array<object>

object

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

code

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

scope

required

string

Allowed values: assessment document requirement

impact

required

string

Allowed values: informational incomplete review_required non_compliant

title

required

minLength(1)

A string at least 1 character(s) long

string

>= 1 characters

explanation

required

minLength(1)

A string at least 1 character(s) long

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

lessThanOrEqualTo(1)

A number less than or equal to 1

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",
    "features_id": "feat_example1042",
    "external_id": "worker-case-1042",
    "external_profile": null,
    "resolved_job_profile_id": null,
    "status": "created",
    "worker": {
      "first_name": "Amina",
      "last_name": "Diallo",
      "date_of_birth": "1990-05-17",
      "nationality": "FR"
    },
    "context": [
      {
        "code": "employment.relationship",
        "value": "posted_employee"
      },
      {
        "code": "employment.employer_country",
        "value": "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": []
    },
    "latest_decision": null,
    "created_at": "2026-08-23T09:30:00Z",
    "updated_at": "2026-08-23T09:30:00Z"
  }
}

400

The request did not match the expected schema

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",
          "worker",
          "nationality"
        ],
        "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"
}

Create assessment

Authorizations

Parameters

Header Parameters

Request Body required

Example

Responses

201

Example

400

Example

401

Example

403

Example

404

Example

409

Example

422

Example

429

Example

500

Example

Request Body^required