Core Concepts

Assessment

The Assessment endpoint is the core functionality of the Compliance Service API. It allows you to evaluate specific input data (documents or URLs) against selected compliance criteria within a framework using a Large Language Model (LLM)-based assessment engine.

This process returns a structured result, including the assessment category, a rationale explaining the decision made by the AI, and citations from the analyzed materials.

Use this endpoint to:

• Run an automated compliance assessment on uploaded documents or URLs.
• Evaluate input data against a specific criterion from a selected framework.
• Retrieve structured assessment results with justifications and source citations.

Run assessment

Code
 
POST /api/v1/assessment

Content-Type: multipart/form-data

Request Parameters

Parameter	Type	Required	Description
assessmentConfiguration	JSON object	Yes	Configuration specifying the assessment details
documents	File array	No*	Multipart files to be assessed
urls	String array	No*	URLs to be assessed

Assessment Configuration Structure

Code
 
{
  "expertId": "string (required)",
  "criterionCodeName": "string (required)", 
  "frameworkCodeName": "string (required)",
  "assessmentProcessId": "string (optional)"
}

Field	Type	Required	Description
expertId	string	Yes	The ID of the expert who carries out the assessment
criterionCodeName	string	Yes	The code name of the criterion on which the assessment is based
frameworkCodeName	string	Yes	The code name of the framework to which the criterion belongs
assessmentProcessId	string	No	The ID of the assessment process, serves to group assessment responses together. If not provided, a new UUID will be generated

Example Request

Code
 
curl --request POST \
  --url /api/v1/assessment \
  --header 'Content-Type: multipart/form-data' \
  --form 'assessmentConfiguration="{
    \"expertId\": \"expert_123\",
    \"criterionCodeName\": \"AC_01\",
    \"frameworkCodeName\": \"ISO_27001\"
  }"' \
  --form 'documents=@document1.pdf' \
  --form 'urls=https://example.com/privacy-policy'

Example Response

Code
 
{
  "id": 7400,
  "assessmentProcessId": "550e8400-e29b-41d4-a716-446655440000",
  "inputTokens": 1475,
  "outputTokens": 362,
  "processingTimeMs": 1340,
  "fileNames": ["document1.pdf"],
  "urls": ["https://example.com/privacy-policy"],
  "frameworkCodeName": "ISO_27001",
  "criterionCodeName": "AC_01",
  "category": "SUFFICIENTLY_REGULATED",
  "rationale": "The privacy policy outlines data subject rights clearly, but lacks contact details for data access requests.",
  "citations": [
    {
      "fileName": "document1.pdf",
      "content": "Users have the right to access their personal data at any time",
      "heading": "Section 4.2",
      "pageNumber": 1,
      "relStartIndex": 0,
      "relEndIndex": 62,
      "absStartIndex": 0,
      "absEndIndex": 62
    },
    {
      "fileName": "privacy-policy.html",
      "content": "We process personal data in accordance with GDPR requirements",
      "heading": "Introduction paragraph",
      "pageNumber": 1,
      "relStartIndex": 0,
      "relEndIndex": 61,
      "absStartIndex": 0,
      "absEndIndex": 61
    }
  ]
}

Response Fields

Field	Type	Description
id	integer	Unique identifier of the assessment response
assessmentProcessId	string	Unique identifier for the assessment run (useful for audits and logs)
inputTokens	integer	Number of tokens used for LLM input (useful for performance tracking)
outputTokens	integer	Number of tokens used for LLM output (useful for performance tracking)
processingTimeMs	integer	Total time taken to complete the assessment, in milliseconds
fileNames	string array	List of input file names used during the assessment
urls	string array	List of URLs used during the assessment
frameworkCodeName	string	Identifier of the framework used for assessment
criterionCodeName	string	Identifier of the criterion used for assessment
category	string	Assessment outcome (see Assessment Categories below)
rationale	string	Human-readable explanation provided by the AI
citations	array	Source citations from the analyzed materials (optional)

Assessment Categories

The assessment can result in one of the following categories:

• SUFFICIENTLY_REGULATED - The assessed material adequately meets the compliance criterion
• NOT_SUFFICIENTLY_REGULATED - The assessed material does not adequately meet the compliance criterion
• MISSING - The required information for the criterion is not present in the assessed material

Citation Structure

When available, citations provide traceability to source materials:

Field	Type	Description
fileName	string	Name of the source material (file name or URL)
content	string	Relevant excerpt from the source material
heading	string	The heading of the reference within the source material
pageNumber	integer	The page number of the reference (if applicable)
relStartIndex	integer	The relative start index of the quoted text (relative to the page)
relEndIndex	integer	The relative end index of the quoted text (relative to the page)
absStartIndex	integer	The absolute start index of the quoted text
absEndIndex	integer	The absolute end index of the quoted text

Submit Assessment Feedback

After the assessment result is displayed, users can provide feedback on the AI's decision. This step is a critical component of the human-in-the-loop process, ensuring that automated decisions remain transparent, accountable, and continuously improving.

Submit Feedback

Code
 
POST /api/v1/assessmentFeedback

Content-Type: application/json

Request Body

Code
 
{
  "assessmentResponseId": 123,
  "expertId": "expert_789", 
  "rationalFeedback": "MFA is only mentioned, not enforced. Therefore, the assessment should be downgraded.",
  "categoryFeedback": "NOT_SUFFICIENTLY_REGULATED"
}

Request Fields

Field	Type	Required	Description
assessmentResponseId	integer	Yes	ID of the assessment response being reviewed
expertId	string	Yes	Identifier of the expert submitting the feedback
rationalFeedback	string	Yes	Detailed rationale justifying agreement or disagreement with the AI assessment
categoryFeedback	string	No	Suggested correct assessment category (if different from AI assessment)

Example Request

Code
 
curl --request POST \
  --url /api/v1/assessmentFeedback \
  --header 'Content-Type: application/json' \
  --header 'X-Keycloak-Subject: your-partner-uuid' \
  --data '{
    "assessmentResponseId": 123,
    "expertId": "expert_789",
    "rationalFeedback": "MFA is only mentioned, not enforced. Therefore, the assessment should be downgraded.",
    "categoryFeedback": "NOT_SUFFICIENTLY_REGULATED"
  }'

Response

The endpoint returns HTTP 200 OK on successful feedback submission.

Why This Matters

This feedback mechanism is designed to integrate human expertise into the compliance evaluation loop. It enhances:

• Trust by giving users control and visibility over AI decisions
• Adaptability through domain-specific refinement and learning
• Auditability by capturing the rationale behind expert decisions
• Quality through continuous improvement of the assessment model

By combining AI-driven automation with structured human input, the Compliance Assessment Service supports a scalable and explainable approach to regulatory evaluations.

Error Handling

The API returns standard HTTP status codes:

• 200 OK - Successful assessment or feedback submission
• 400 Bad Request - Invalid request parameters or missing required fields
• 401 Unauthorized - Invalid or missing authentication
• 409 Conflict - Assessment processing error or system conflict

Error responses include descriptive messages to help troubleshoot issues.