Contract Manager API Documentation

Introduction

The Contract Manager API provides a structured interface for managing legal contracts and their sub-components, such as sub-contracts, actions, verification entries, and constraints. It supports creation, updating, and deletion of a full contract specification using a single JSON payload. The system is designed for modular extensibility and supports clean sub-document isolation.

Architecture

The Contracts System is a distributed, extensible, and event-driven framework for managing digital legal contracts and their lifecycle, including creation, updates, execution, verification, and querying. It supports both REST and GraphQL interfaces for managing nested contract structures such as sub-contracts, actions, constraints, and verification entries.

Designed with modular service boundaries and asynchronous dispatch layers, the system enables contract logic to be enforced via programmable workflows (DSL), SLA metrics, and dynamic verification processes. Real-time updates, validations, and action outcomes are processed through an internal message queue and a routing fabric integrated with Kubernetes and service-level event listeners.

contracts-system

Download Image

1. Contract Lifecycle Management Service

This subsystem manages the creation, update, and deletion of complete contracts and their nested components using a REST interface. It includes a spec parser that converts complex JSON inputs into database-ready entries and routes them to specialized service modules for execution.

Controller

The primary interface for the contract lifecycle service. It processes incoming REST API requests and routes them to the appropriate internal module (creator, updater, deleter). It also invokes the spec parser and performs initial validation checks.

Spec Parser

Responsible for decomposing a hierarchical contract JSON into normalized components such as Contract, SubContract, Action, VerificationEntry, and Constraint. These objects are transformed into formats compatible with database persistence modules.

Creator Module

Handles the insertion of new contract specifications into the database. This module ensures data integrity and atomicity across nested records during initial contract creation.

Updater Module

Processes update operations for contracts and their components. It performs version checks and ensures logical consistency when contract data is modified after creation.

Deletion Module

Responsible for cascading deletion of a contract and all of its sub-components. It ensures that no orphan sub-contracts or actions remain after deletion.

2. Contract Execution and Verification Engine

This module governs the runtime behavior of sub-contracts, including verification workflows, action execution, SLA evaluations, and real-time response dispatch. It is designed to operate in a decentralized queue-based environment, with per-instance event routing and asynchronous acknowledgement handling.

Action Dispatcher

Acts as the orchestration hub for sub-contract executions. It processes input events (typically from REST or WebSocket), determines whether a verification or action must be triggered, and dispatches the task accordingly.

Sub-Contract Status Updater

This component modifies the sub-contract’s status field based on fulfillment conditions defined in the spec. It ensures that each action or verification is correctly reflected in the sub-contract lifecycle.

Verification Subject Notifier

Sends messages on the internal messaging mesh to notify assigned verifiers (subjects) that a verification is required. These may include users, services, or agent systems.

DSL Workflow Invocation Module

Executes a programmable workflow (via DSL) associated with an action or verification. The result is evaluated to determine fulfillment or failure.

Verification Result Updater

Handles the final processing of verification workflows, updating the contract or triggering a follow-up action as dictated by the result.

Action Result Updater

Performs downstream logic once an action is fulfilled — such as transitioning to the next clause, verifying conditions, or updating the DB.

Adhoc Verification Session Handler

Allows verifiers to initiate on-demand verification checks, dynamically mapped to contracts that support periodic or event-based assessments.

Report Generator and Delivery

Generates final reports once all contract actions are complete. Reports are linked to associated subjects and stored via URL references in the DB.

Metrics Webhook Handler

Evaluates metric-based constraints by integrating with SLA/observability systems. If a contract defines metric conditions, this module verifies compliance.

Acknowledgement System

Sends completion signals back to the origin subject once verification or action execution is complete.

Contract Queue and Routing Subsystem

This layer enables routing of contract-specific events to the correct processing queue based on the contract session or subject. It integrates with Kubernetes event listeners and maintains dynamic routing tables for distributing contract workloads.

Queue Controller

Handles queue registration, scaling, and session-to-queue assignments. It also processes REST submissions for new tasks tied to contracts.

Router

Resolves routing targets based on subject_id or session_id. It dynamically assigns events to queues and updates the routing map as required.

Routing Table / Queue Map

A stateful table that maps session_id to internal queue identifiers. It is updated by the controller and used by the router for dispatch.

Kubernetes Events Listener

Watches cluster-level events and updates queue availability. This enables dynamic scaling and worker queue discovery in distributed deployments.

Per-Instance Event Queues

Each active processing instance maintains a queue for incoming contract events. These queues are fed by the router based on session routing logic.

4. Contract Query and Report System

System Overview

This subsystem allows external systems and users to query contracts, sub-documents, and generate compliance reports. It offers both REST and GraphQL interfaces, and supports full contract retrievals as well as filtered sub-queries.

Component Descriptions

Query Controller

Handles incoming REST and GraphQL queries. It supports filtering, search indexing, and joining of sub-components to return composite responses.

Search and Query System

Provides high-level search across contract metadata such as status, party ID, type, and creation timestamp. Used for audits and organizational indexing.

Report Generator

Constructs a downloadable or renderable report of the full contract. Includes execution logs, verification timestamps, and outcomes.

GraphQL Plugin

Enables flexible, nested querying of contract objects using GraphQL syntax. This allows custom clients to extract specific sub-structures efficiently.

Schema

The complete contract is composed of a top-level Contract object and associated sub-components:

Data Classes

@dataclass
class Contract:
    contract_id: str
    contract_type: str
    contract_parties_ids: List[str]
    contract_parent_org_id: str
    contract_acl_data: Dict
    contract_acl: Dict
    contract_sub_clauses_id: List[str]
    contract_status: str
    contract_creation_time: str
    last_update_time: str
    contract_final_completion_timestamp: Optional[str]
    final_verifier_id: Optional[str]
    report_url: Optional[str]
    purpose: Optional[str]
    human_readable_description: Optional[str]
    json_parseable_description: Optional[str]
    contract_parties_roles_mapping: Dict

@dataclass
class SubContract:
    sub_contract_id: str
    contract_id: str
    sub_contract_clause_data: List[Dict]
    sub_contract_json_repr: Dict
    sub_contract_parties_ids: List[str]
    sub_contract_status: str
    sub_contract_actions_map: Dict
    sub_contract_verification_map: Dict
    sub_contract_creation_time: str
    last_update_time: str
    sub_report_url: Optional[str]
    verification_subjects_list: Optional[List[str]]
    purpose: Optional[str]
    json_parseable_description: Optional[str]
    sub_clause_constraints: Optional[List[str]]
    sub_contract_parties_roles_mapping: Optional[Dict]
    human_readable_description: Optional[str]

@dataclass
class Action:
    action_id: str
    sub_clause_id: str
    action_type: str
    action_fulfillment_dsl_workflow_id: str
    action_execution_status: str
    action_execution_config: Dict
    action_outcome_data: Optional[Dict]
    action_execution_ppt_dsl: Optional[str]
    action_execution_constraint_ids: Optional[List[str]]

@dataclass
class VerificationEntry:
    verification_entry_id: str
    sub_clause_action_type: str
    verifier_subject_id: str
    verifier_subject_type: str
    verification_dsl_workflow_id: str
    verification_mode: str
    verification_config: Dict
    verification_status: str
    verification_outcome_data: Dict
    verification_outcome_action_id: Optional[str]
    verification_timestamp: Optional[str]
    verification_cert_data: Optional[Dict]
    sub_clause_id: str

@dataclass
class SubContractConstraint:
    constraint_id: str
    sub_clause_id: str
    constraint_type: str
    constraint_sub_type: Optional[str]
    constraint_parameters: Dict
    constraint_policy_id: Optional[str]
    constraint_negotiation_parameters: Optional[Dict]
    group_ids: Optional[List[str]]
    role_ids: Optional[List[str]]
    can_negotiate: Optional[bool] = False

Contract Fields

Field	Description
`contract_id`	Unique contract identifier
`contract_type`	Type/category of the contract (e.g. service, employment)
`contract_parties_ids`	List of participating entity IDs
`contract_parent_org_id`	Organization under which this contract is made
`contract_acl_data`	Raw ACL metadata
`contract_acl`	Evaluated ACL structure
`contract_sub_clauses_id`	IDs of referenced clauses
`contract_status`	Status such as active, expired, etc.
`contract_creation_time`	Time of initial creation (ISO format)
`last_update_time`	Last time contract was updated
`contract_final_completion_timestamp`	When it was marked as completed
`final_verifier_id`	Who verified the final contract
`report_url`	External report link if available
`purpose`	Purpose of this contract
`human_readable_description`	Readable description for end users
`json_parseable_description`	JSON-compatible description for processing
`contract_parties_roles_mapping`	Role mapping for parties

SubContract Fields

Field	Description
`sub_contract_id`	Unique ID for the sub-contract
`contract_id`	Reference to parent contract
`sub_contract_clause_data`	List of clauses inside sub-contract
`sub_contract_json_repr`	Full JSON dump for machine processing
`sub_contract_parties_ids`	Parties involved in the sub-contract
`sub_contract_status`	Current status of the sub-contract
`sub_contract_actions_map`	Mapping of all actions in this sub-contract
`sub_contract_verification_map`	Mapping of all verifications in this sub-contract
`sub_contract_creation_time`	When this sub-contract was created
`last_update_time`	When last updated
`sub_report_url`	Link to sub-contract report if available
`verification_subjects_list`	Subjects that will perform verification
`purpose`	Purpose of this sub-contract
`json_parseable_description`	JSON-compatible description for parsing
`sub_clause_constraints`	List of constraint IDs applied to this sub-contract
`sub_contract_parties_roles_mapping`	Roles and parties mapping
`human_readable_description`	Human-readable format

Action Fields

Field	Description
`action_id`	Unique ID for action
`sub_clause_id`	Clause this action is tied to
`action_type`	Type of action (e.g. approve, sign)
`action_fulfillment_dsl_workflow_id`	Workflow to fulfill this action
`action_execution_status`	Status of action execution
`action_execution_config`	Runtime configuration for the action
`action_outcome_data`	Output of the action if completed
`action_execution_ppt_dsl`	Optional DSL for UI display
`action_execution_constraint_ids`	Related constraints for this action

VerificationEntry Fields

Field	Description
`verification_entry_id`	ID for the verification entry
`sub_clause_action_type`	Action type being verified
`verifier_subject_id`	ID of verifier subject
`verifier_subject_type`	Type (e.g., user, role) of verifier
`verification_dsl_workflow_id`	Verification logic workflow ID
`verification_mode`	Manual, automatic, etc.
`verification_config`	Input config for execution
`verification_status`	Status of verification
`verification_outcome_data`	Data produced from verification
`verification_outcome_action_id`	Outcome action ID if chained
`verification_timestamp`	Timestamp of verification event
`verification_cert_data`	Certificate if any generated
`sub_clause_id`	Clause verified by this entry

SubContractConstraint Fields

Field	Description
`constraint_id`	Unique ID for constraint
`sub_clause_id`	Clause it constrains
`constraint_type`	Main type of constraint
`constraint_sub_type`	Further classification of constraint
`constraint_parameters`	Raw parameter dict for enforcement
`constraint_policy_id`	ID of referenced policy if any
`constraint_negotiation_parameters`	Params to support negotiation if allowed
`group_ids`	Restricted to these group IDs
`role_ids`	Restricted to these role IDs
`can_negotiate`	Boolean toggle to allow negotiation

3. API Documentation

3.1 Create Contract

Endpoint: POST /contract

Description: Upload a full contract JSON including all nested components.

Request Body:

{
  "contract": { ... },
  "sub_contracts": [ ... ],
  "actions": [ ... ],
  "verification_entries": [ ... ],
  "constraints": [ ... ]
}

Response:

{
  "success": true,
  "message": "Contract created successfully",
  "result": { ... }
}

cURL Example:

curl -X POST http://localhost:5000/contract \
     -H "Content-Type: application/json" \
     -d @full_contract.json

3.2 Update Contract

Endpoint: PUT /contract

Description: Update the contract or any of its sub-documents.

Request Body: Same as Create Contract

Response:

{
  "success": true,
  "message": "Contract updated successfully",
  "result": { ... }
}

cURL Example:

curl -X PUT http://localhost:5000/contract \
     -H "Content-Type: application/json" \
     -d @updated_contract.json

3.3 Delete Full Contract

Endpoint: DELETE /contract/<contract_id>

Description: Deletes the contract and all related subdocuments (cascading delete).

Response:

{
  "success": true,
  "message": "Contract and subdocuments deleted",
  "result": { ... }
}

cURL Example:

curl -X DELETE http://localhost:5000/contract/contract_abc_123

3.4 Delete Sub-Document

Endpoint: DELETE /contract/subdocument/<doc_type>/<doc_id>

Description: Delete a single sub-document by type and ID.

doc_type values: sub_contract, action, verification_entry, constraint

Response:

{
  "success": true,
  "message": "<doc_type> deleted",
  "result": 1
}

cURL Example:

curl -X DELETE http://localhost:5000/contract/subdocument/action/action_123

Query APIs

API: Get Full Contract Report

Endpoint: GET /contract/<contract_id>/report

Description: Fetches the complete contract specification including all associated sub-documents:

Contract
Sub-contracts
Actions
Verification Entries
Constraints

Path Parameters

Parameter	Type	Required	Description
`contract_id`	string	Yes	ID of the contract to be retrieved

Response Format

Success (200 OK):

{
  "success": true,
  "data": {
    "contract": { ... },
    "sub_contracts": [ ... ],
    "actions": [ ... ],
    "verification_entries": [ ... ],
    "constraints": [ ... ]
  }
}

Not Found (404):

{
  "success": false,
  "error": "Contract with ID '...' not found."
}

Error (500):

{
  "success": false,
  "error": "Internal error message"
}