Configure Job Profiles

This example creates a Site worker profile with a Basic Safety requirement. Use a workspace credential with workspace-configuration:read and job-profiles:write, or open Job Profiles in the customer control plane.

1. Read the authoring catalog

Request GET /v1/policy-authoring-catalog. It lists available facts, document types, qualification IDs, assurance levels and comparison policies. A catalog qualification may exist before its specification or recognition support is available. Use stable IDs, rather than display names, for known qualifications.

2. Create the profile and draft

Send POST /v1/job-profiles:

{ "code": "site-worker", "title": "Site worker" }

Send {} to POST /v1/job-profiles/{id}/drafts. Save the returned revision ID and lock_version. For a subsequent revision, include the profile’s current active_revision as expected_active_revision.

3. Map your job identifier

Send this command to POST /v1/job-profiles/{id}/revisions/{revision_id}/commands, using the current lock version:

{
  "expected_lock_version": 1,
  "command": {
    "kind": "upsert_external_reference",
    "namespace": "contract_management",
    "value": "SITE_WORKER"
  }
}

An active (namespace, value) pair resolves to one Job Profile within your workspace. Use the new lock version returned after every command.

4. Add Basic Safety

Send a generic upsert_rule command to the same endpoint:

{
  "expected_lock_version": 2,
  "command": {
    "kind": "upsert_rule",
    "rule_code": "basic_safety",
    "label": "Basic Safety",
    "applies_when": { "kind": "always" },
    "enforcement": "required",
    "expectation": {
      "kind": "technical_requirement",
      "accepted_qualifications": [
        {
          "reference_id": "accepted-course-a",
          "label": "First customer-approved qualification",
          "qualification_definition_id": null
        },
        {
          "reference_id": "accepted-course-b",
          "label": "Second customer-approved qualification",
          "qualification_definition_id": null
        }
      ],
      "comparison_policy": { "mode": "accepted_only" },
      "minimum_assurance": "document_supported",
      "uploaded_proof_required": true
    }
  }
}

Replace the labels with your actual acceptance list. Link known entries using catalog IDs. Keep unknown entries unlinked and retain their stable reference IDs; these entries remain unresolved until their identity can be established. Any one accepted, valid qualification with the required proof can satisfy the requirement.

You can also add criteria and set comparison_policy.mode to compare to assess other qualifications against your training and examination requirements. See Training and examination criteria for the full shape and outcome choices. Criteria can be combined with the acceptance list, or used with an empty list.

5. Preview and activate

Send {} to POST /v1/job-profiles/{id}/revisions/{revision_id}/preview. Review issues and effective_rules. Activate a valid revision with POST /v1/job-profiles/{id}/revisions/{revision_id}/activate:

{ "expected_lock_version": 3 }

Activation freezes the profile revision and available catalog revision pins, and queues reevaluation of existing Assessments that use the affected job reference. Earlier Decisions remain unchanged. Pending qualification entries are valid configuration; they record acceptance while recognition is added.

6. Select the profile for an Assessment

Include this reference when creating an Assessment:

{
  "job": {
    "namespace": "contract_management",
    "external_id": "SITE_WORKER"
  }
}

Dockt resolves the profile within the Assessment’s workspace. You do not send profile IDs or qualification rules on the Assessment.

Continue with Complete an Assessment to provide worker context and evidence. Reconciliation links existing pending entries as recognition improves, including when catalog names differ from your own names.