Overview

Getting Started

This page outlines the recommended integration flow for building an own service that communicates effectively with the Compliance Assessment Service. The objective is to deliver a consistent and user-friendly experience while leveraging the full capabilities of the backend service.

The API provides a range of endpoints designed to integrate with both existing and newly built applications. Below are the key recommendations for effective integration:

Retrieve Supported Compliance Frameworks

Use the /api/v1/frameworks endpoint to fetch the list of compliance frameworks supported by the service.

Code
GET /api/v1/frameworks

Use this list to present framework options to users so they can select a relevant framework to initiate assessments across multiple criteria.

Retrieve Criteria Within a Framework

Use the /api/v1/frameworks/{frameworkId}/criteria endpoint to retrieve the list of criteria associated with a specific framework.

Code
GET /api/v1/frameworks/{frameworkId}/criteria

This allows users to select individual criteria they wish to assess using the automated evaluation process.

Run Automated Assessments

The /api/v1/assessments endpoint is the core of the service. It accepts multipart/form-data requests with a configuration object, documents, and/or URLs.

Code
POST /api/v1/assessments

Allow users to select appropriate input data (e.g., documents or URLs) before running the assessment.
Support the ability to reject AI-generated results and override them with human-evaluated results if necessary.

The effectiveness of the assessment is highly dependent on the relevance and completeness of the input data.
At least one input document or URL is required to initiate an assessment.

Preprocess Content

Before running an assessment, you can optionally preprocess input materials (documents or URLs) using the Content Processing endpoints. This allows you to:

Submit files or URLs for text extraction ahead of time
Check the processing status to know when content is ready
Retrieve the extracted text for review or display

Code
POST /api/v1/content-processing/file
POST /api/v1/content-processing/url

Content processing is especially useful when you want to show users the extracted text from their uploaded documents or URLs before running an assessment.

Submit Feedback on Assessment Results

For continuous improvement of the AI's evaluation accuracy, it is essential to collect structured feedback. Use the /api/v1/assessmentFeedback endpoint for this purpose.

Code
POST /api/v1/assessmentFeedback

Always provide an option for users to give feedback when rejecting an assessment result.
Enforce a minimum character count on feedback input to ensure useful information is collected.

By following these recommendations, your application will be able to provide a robust and adaptive compliance evaluation experience powered by the Compliance Assessment Service.

For details on individual endpoints, refer to the dedicated API Reference Pages.

Quickstart: First API Call in 5 Steps

This section guides you through running your first compliance assessment using the Compliance Assessment Service.

Prerequisites

Active contract and credentials from our team (client_id, client_secret, username, password)
Your preferred HTTP client (e.g. curl, Postman, or code)

1. Obtaining an Access Token

To acquire an access token, clients must authenticate against the Keycloak token endpoint using the Resource Owner Password Credentials (ROPC) grant type. This is typically used in trusted applications (e.g. CLI tools, backend services) where the application itself handles user credentials.

Code
curl -X POST https://compliance-assessment.precognox.com/keycloak/realms/master/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=<your-username>" \
  -d "password=<your-password>" \
  -d "client_id=<your-api-client-id>" \
  -d "client_secret=<your-client-secret>" \
  -d "grant_type=password"

Save the access_token from the response. You'll need it for all authenticated requests.

2. List Available Compliance Frameworks

Code
curl -X GET https://compliance-assessment.precognox.com/api/v1/frameworks \
  -H "Authorization: Bearer <access_token>"

This returns a list of supported frameworks (e.g., GDPR_DPA), including their codeName and available criteria.

3. Run an Assessment

From the list of compliance frameworks and criteria, select a framework with criteria to assess the selected material. In this example, we will run an assessment with GDPR_DPA as framework and PLACE_OF_PROCESSING for criterion.

The assessment endpoint accepts multipart/form-data with a JSON configuration part and file/URL parts:

Code
curl -X POST https://compliance-assessment.precognox.com/api/v1/assessments \
  -H "Authorization: Bearer <your-access_token>" \
  -H "Content-Type: multipart/form-data" \
  -F 'configuration={"expertId":"<your-expert-id>","frameworkCodeName":"GDPR_DPA","criteriaCodeNames":["PLACE_OF_PROCESSING"]};type=application/json' \
  -F 'documents=@doc_001.pdf'

The response confirms the assessment has been accepted for asynchronous processing:


Code
{
  "assessmentProcessId": "62227aea-5576-49af-9cf7-f90f9473d71a",
  "status": "PENDING",
  "completion": 0.0,
  "responses": []
}

3b. Poll for Results

The assessment runs asynchronously. Poll the status endpoint until status is COMPLETED, then fetch the results:

Code
# Poll status
curl -X GET https://compliance-assessment.precognox.com/api/v1/assessments/62227aea-5576-49af-9cf7-f90f9473d71a/status \
  -H "Authorization: Bearer <your-access_token>"

# When completed (303 redirect or status=COMPLETED), get results
curl -X GET https://compliance-assessment.precognox.com/api/v1/assessments/62227aea-5576-49af-9cf7-f90f9473d71a/result \
  -H "Authorization: Bearer <your-access_token>"

The result includes the category and rationale for each assessed criterion:


Code
[
  {
    "id": 1,
    "assessmentProcessId": "62227aea-5576-49af-9cf7-f90f9473d71a",
    "inputTokens": 5442,
    "outputTokens": 109,
    "processingTimeMs": 5852,
    "expertId": "<your-expert-id>",
    "fileNames": ["doc_001.pdf"],
    "urls": [],
    "frameworkCodeName": "GDPR_DPA",
    "criterionCodeName": "PLACE_OF_PROCESSING",
    "category": "MISSING",
    "rationale": "The DPA does not address whether data processing outside the company premises is permitted or prohibited...",
    "citations": []
  }
]

4. Submit Feedback (Human-in-the-Loop)

Disagree with the AI’s decision? Submit feedback to correct misclassifications and enhance model performance over time.

Code
curl -X POST https://compliance-assessment.precognox.com/api/v1/assessmentFeedback \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "assessmentResponseId": 1,
    "expertId": "<your-expert-id>",
    "rationalFeedback": "The document lacks clarity on user access levels.",
    "categoryFeedback": "NOT_SUFFICIENTLY_REGULATED"
  }'

We can use your feedback to further improve the accuracy of future assessments.

What’s Next?

Explore the full API Reference Page for more endpoints
Check out Authentication for token refresh and error handling
Need help? Contact your integration support contact

Last modified on May 28, 2026

Service Description Authentication