Other Articles

How to integrate API for Consent Management?

Support > Consent Management Integration

11 February, 2026

Overview

The Consents API allows you to record, retrieve, and audit user consent decisions in a structured and compliant way.

A consent is a time-stamped event that records whether a user agreed to, rejected, or revoked a specific document or agreement — such as a Privacy Policy, Terms of Service, or marketing consent.

This API is designed for:

  • Legal defensibility
  • Audit readiness
  • Versioned policy tracking
  • Immutable consent history

Base URL 

https://in.kawach.ai/api

All endpoints are prefixed with: 

/api

Why Consent Matters

Consent is not a static flag — it is an event in time.

Each record captures:

  • Who made the decision
  • What document they responded to
  • Which version of that document
  • When the decision occurred
  • What the decision was

Consent records are immutable.

If a user changes their decision, you must create a new consent event.

This ensures a complete, tamper-resistant audit trail.

Authentication

All requests must include the following headers: 


x-client-id: <YOUR_CLIENT_ID>
x-client-secret: <YOUR_CLIENT_SECRET>

These headers identify your organization context.

Core Concepts

Actor (User)

The actor is the person providing consent.

Actors are identified using your internal identifier such as:

  • user_id
  • customer_id
  • account_id

Artifact (Document)

The artifact is the document being consented to.

  • Privacy Policy
  • Terms of Service
  • Marketing Consent
  • Cookie Policy

Artifacts are identified using your own internal identifier, such as:

  • privacy_policy
  • terms_v2
  • marketing_opt_in

Artifacts may have versions (e.g., v1, v2).

API Endpoints

1. Create Consent 

POST /api/consent

Creates a new immutable consent event.

You must call this endpoint whenever a user:

  • Accepts a policy
  • Declines a policy
  • Revokes consent
  • Accepts a new version

Request Fields

Below is the complete list of supported fields:

Required Fields

  • actor_identifier (string)
    Unique identifier of the user in your system.
  • artifact_identifier (string)
    Unique identifier of the document being consented to.
  • status (string)
    Consent decision. Allowed values:
    • given
    • revoked
    • declined
  • type (string)
    Type of consent being recorded (e.g., privacy_policy, cookie, terms).

Required on First Artifact Creation

These fields must be provided the first time an artifact is referenced:

  • artifact_name (string)
    Display name of the document.
  • artifact_type (string)
    Type of artifact (e.g., policy, terms, agreement).

Optional Fields

  • actor_name (string)
    User’s display name.
  • actor_email (string)
    User’s email address.
  • artifact_status (string)
    Status of the artifact:
    • active
    • draft
    • deprecated
  • artifact_version (string)
    Version of the document (e.g., v1, v2).
  • event_timestamp (ISO 8601 UTC string)
    Time when the consent occurred. If not provided, server time is used.
  • source (string)
    Where consent was captured (e.g., web, mobile, api).
  • ip_address (string)
    IP address of the user at the time of consent.

Example Request:


{
"actor_identifier": "user_123",
"actor_name": "John Doe",
"actor_email": "john@example.com",
"artifact_identifier": "privacy_policy",
"artifact_name": "Privacy Policy",
"artifact_type": "policy",
"artifact_status": "active",
"artifact_version": "v2",
"status": "given",
"event_timestamp": "2026-01-22T10:30:00Z",
"source": "web",
"type": "privacy_policy",
"ip_address": "127.0.0.1"
}

Implementation Examples

Code Snippets - Create Consent 


        


      


    


    

    

      2. Get Consent by ID
    


    

      
      
GET /api/consent/:id

      

      
Retrieves a single consent event by its unique ID.

      
Example Response:


      

        
        

{
"data": {
"id": "uuid",
"type": "privacy_policy",
"status": "given",
"event_timestamp": "2026-01-22T10:30:00Z",
"source": "web",
"ip_address": "127.0.0.1"
}
}



      


      

        3. List Consents
      


      

        
        
GET /api/consents

      

      

      
Retrieves consent records with optional filters.


      
Supported Query Parameters:


      
    
        
  • actor_identifier — filter by user
    • 
        
  • artifact_identifier — filter by document
    • 
        
  • artifact_version — filter by document version
    • 
        
  • status — filter by consent decision
    • 
        
  • search_query — search by:
          
      
            
    • consent ID
      • 
            
    • actor_identifier
      • 
            
    • actor_email
      • 
          
    
        
    • 
      


      
Example Response:


      

        
        

{
"data": {
"records": [
{
"id": "uuid",
"type": "privacy_policy",
"status": "given",
"event_timestamp": "2026-01-22T10:30:00Z"
}
]
}
}



      


    


    
    

      

        Implementation Examples
      

      
      


        

          Code Snippets - List Consents
        


        


          


            


            

          


          

            

          


        


      


      
    

    
    

      

        Best Practices
      


      
    
        
  • Always create a new consent event when a user changes their decision.
    • 
        
  • Include artifact_version whenever you release updated artifacts.
    • 
        
  • Store consent at the moment the user acts — not retroactively.
    •