Test your integration

Test your Dockt integration in a separate Workspace before you send production worker data. A Workspace isolates credentials, configuration, Documents, Assessments, Decisions, Notification Destinations, and event routes.

Dockt uses https://api.dockt.com for public API traffic. The API does not expose a request flag that changes an operation into test mode. Use Workspace isolation to keep test data and production data separate.

Create a test environment

Set up a Workspace used only by developers and automated tests:

1. Enable the same social compliance packages you plan to use in production.
2. Create a workspace credential with only the permissions your tests need.
3. Create a webhook destination owned by your test environment and configure its event routes.
4. Use fictional or synthetic personal data that you are authorized to process.
5. Keep every test external_id and idempotency key free of personal data.

Do not run integration tests in a production Workspace. Assessments do not have a delete operation, and their immutable Decisions remain part of that Workspace’s history.

Separate parser tests from processing tests

Use two kinds of tests:

• Contract tests verify that your code handles every documented response shape and enum.
• API workflow tests verify authentication, uploads, asynchronous state changes, notification delivery, and recovery against the public API.

Do not require an arbitrary uploaded file to produce one exact semantic result in every automated test. Use curated OpenAPI examples for deterministic parser tests, and use API workflow tests to verify transport and lifecycle behavior.

Extract response fixtures from OpenAPI

Download the public contract in your test setup:

curl --fail-with-body --silent --show-error \
  https://api.dockt.com/openapi.json \
  --output openapi.json

Extract a curated example, such as the accepted Document upload response:

jq '.paths["/v1/documents"].post.responses["202"].content["application/json"].example' \
  openapi.json > document-uploaded.json

Use the same approach for:

• POST /v1/assessments with response 201.
• GET /v1/documents/{documentId} with response 200.
• GET /v1/assessments/{assessmentId} with response 200.
• GET /v1/decisions/{decisionId} with response 200.
• Any documented Problem Details response.

Store the extracted examples with your tests or regenerate them in a reviewed dependency-update process. Don’t download a changing contract during every production build.

Test the first API boundary

Cover these cases in your test suite:

Case	Expected behavior
Valid workspace credential	GET /v1/auth/me returns the expected Workspace and permissions.
Missing bearer token	The API returns 401 with Problem Details.
Missing permission	The API returns 403 with Problem Details.
Empty or unsupported upload	The API returns the documented invalid-upload Problem Details response.
Same idempotency key and request	Dockt replays the successful response.
Same idempotency key with a changed body	Dockt returns an idempotency conflict.

Record x-request-id when a test fails. Do not record the credential or uploaded file content.

Test asynchronous state handling

For Documents, verify that your application:

• Stores the Document ID from the 202 Accepted response.
• Handles uploaded, processing, completed, failed, and withdrawn.
• Reads document_result only after status is completed.
• Distinguishes a processing failed status from an invalid result.
• Handles unknown future issue, Finding, and classification codes safely.

For Assessments, verify that your application:

• Uses input_requests to supply values already known by your system without asking users to complete a questionnaire.
• Shows one short explanation when Dockt has too little information to check the worker, instead of listing every missing field.
• Uses the Assessment’s requirements instead of a fixed upload checklist.
• Handles a Decision created from zero or partial evidence, including an incomplete Decision with outstanding input_requests.
• Handles all four Decision values: compliant, incomplete, review_required, and non_compliant.
• Stores the Decision ID and assessment_input_version it used.
• Detects when a later update creates a newer Decision.

Test webhook destinations

Use POST /v1/notification-destinations/{notificationDestinationId}/test to send a signed notification_destination.test event. Verify that your receiver:

1. Reads the raw body before parsing JSON.
2. Rejects an invalid signature.
3. Rejects a timestamp outside the five-minute replay window.
4. Stores the event ID before applying side effects.
5. Returns 2xx after durable acceptance.
6. Treats a repeated event ID as an acknowledged duplicate.

The test event proves delivery and signature handling. It does not create a Document, Assessment, or Decision.

Test recovery

Simulate failures in your own application:

• Drop one notification after signature verification, then recover with a canonical API read.
• Deliver the same notification event twice, then confirm that the side effect runs once.
• Deliver events in a different order, then confirm that you fetch current resource state.
• Time out an upload request, then retry with the same idempotency key and body.
• Leave a resource unresolved past your application’s deadline, then confirm that you keep it pending instead of inventing a result.

Finish by reviewing Prepare for production.