Format Comparison

Overview

The Format Comparison endpoint compares document formatting elements like margins, links, and font sizes across two different documents. This powerful tool enables detailed format analysis by extracting and comparing specific formatting checkpoints from uploaded files.

Use this endpoint to:

Compare page margins across two documents
Analyze link differences between documents
Compare font sizes and typography
Validate formatting consistency
Build document quality assurance workflows

Endpoint Details

Method: POST
Endpoint: /api/agent/format_comparison
Base URL: https://api.k-v.ai
Authentication: Access Key (Required)

Request Specification

Headers

Header	Type	Required	Description
access-key	string	Yes	Your unique access-key generated from the platform UI
Content-Type	string	Yes	Must be application/json

Request Body

{
    "doc_1_process_id": "bca03f7db29b5f22c293f6cff2bf378a",
    "doc_2_process_id": "264dfa262b748d15ccbeaada89430c68",
    "checkpoints_to_compare": {
        "page_margins": true,
        "links": true,
        "font_sizes": false
    }
}

Body Fields

Field	Type	Required	Description
doc_1_process_id	string	Yes	First document ID to compare (obtained from Upload or List Documents APIs)
doc_2_process_id	string	Yes	Second document ID to compare (obtained from Upload or List Documents APIs)
checkpoints_to_compare	object	Yes	Formatting elements to compare (set to true to include, false to exclude)
checkpoints_to_compare.page_margins	boolean	Yes	Compare page margins (top, bottom, left, right)
checkpoints_to_compare.links	boolean	Yes	Compare links and hyperlinks in documents
checkpoints_to_compare.font_sizes	boolean	Yes	Compare font sizes throughout documents

Response Specification

Success Response (200 OK)

{
    "data": [
        {
            "file_name": "john_smith_story.pdf",
            "result": {
                "page_margins": {
                    "1": {
                        "top": 1.07,
                        "bottom": 3.95,
                        "left": 1.08,
                        "right": 1.08
                    },
                    "2": {
                        "top": 1.07,
                        "bottom": 3.92,
                        "left": 1.08,
                        "right": 1.08
                    },
                    "3": {
                        "top": 1.07,
                        "bottom": 2.12,
                        "left": 1.08,
                        "right": 1.08
                    }
                },
                "links": []
            },
            "doc_hash": "bca03f7db29b5f22c293f6cff2bf378a"
        },
        {
            "file_name": "Settlement Agreement (1).pdf",
            "result": {
                "page_margins": {
                    "1": {
                        "top": 1.15,
                        "bottom": 1.21,
                        "left": 1.25,
                        "right": 1.23
                    },
                    "2": {
                        "top": 0.98,
                        "bottom": 1.04,
                        "left": 1.25,
                        "right": 1.21
                    },
                    "3": {
                        "top": 0.99,
                        "bottom": 4.19,
                        "left": 1.25,
                        "right": 1.16
                    }
                },
                "links": []
            },
            "doc_hash": "264dfa262b748d15ccbeaada89430c68"
        }
    ],
    "message": "Format compared successfully"
}

Response Fields

Field	Type	Description
data	array	Array containing format analysis for both documents
data[].file_name	string	Original filename of the document
data[].result	object	Format analysis results based on requested checkpoints
data[].result.page_margins	object	Page-by-page margin measurements (if requested)
data[].result.page_margins[page_number]	object	Margin measurements for specific page
data[].result.page_margins[page_number].top	number	Top margin in inches
data[].result.page_margins[page_number].bottom	number	Bottom margin in inches
data[].result.page_margins[page_number].left	number	Left margin in inches
data[].result.page_margins[page_number].right	number	Right margin in inches
data[].result.links	array	List of hyperlinks found in document (if requested)
data[].result.font_sizes	array/object	Font sizes used in document (if requested)
data[].doc_hash	string	Document process ID
message	string	Human-readable response message

Error Responses

401 Unauthorized

{
    "data": {},
    "message": "Invalid or missing access key"
}

Cause: Missing or invalid access-key header.

400 Bad Request - Invalid Document IDs

{
    "data": {},
    "message": "Invalid docs selected"
}

Causes:

Missing or invalid doc_1_process_id or doc_2_process_id
Documents don't exist in your account
Documents are not yet processed (status is not processed)

500 Internal Server Error - General Error

{
    "data": {},
    "message": "Something went wrong"
}

Causes:

Server-side processing error
Documents cannot be parsed for format extraction

Code Snippets

curl --location 'https://api.k-v.ai/api/agent/format_comparison' \
--header 'access-key: YOUR_ACCESS_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "doc_1_process_id": "bca03f7db29b5f22c293f6cff2bf378a",
    "doc_2_process_id": "264dfa262b748d15ccbeaada89430c68",
    "checkpoints_to_compare": {
        "page_margins": true,
        "links": true,
        "font_sizes": false
    }
}'

import requests
import json

url = "https://api.k-v.ai/api/agent/format_comparison"

payload = json.dumps({
    "doc_1_process_id": "bca03f7db29b5f22c293f6cff2bf378a",
    "doc_2_process_id": "264dfa262b748d15ccbeaada89430c68",
    "checkpoints_to_compare": {
        "page_margins": True,
        "links": True,
        "font_sizes": False
    }
})

headers = {
    'access-key': 'YOUR_ACCESS_KEY',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

const axios = require('axios');

let data = JSON.stringify({
    "doc_1_process_id": "bca03f7db29b5f22c293f6cff2bf378a",
    "doc_2_process_id": "264dfa262b748d15ccbeaada89430c68",
    "checkpoints_to_compare": {
        "page_margins": true,
        "links": true,
        "font_sizes": false
    }
});

let config = {
    method: 'post',
    maxBodyLength: Infinity,
    url: 'https://api.k-v.ai/api/agent/format_comparison',
    headers: { 
        'access-key': 'YOUR_ACCESS_KEY',
        'Content-Type': 'application/json'
    },
    data: data
};

axios.request(config)
.then((response) => {
    console.log(JSON.stringify(response.data, null, 2));
})
.catch((error) => {
    console.log(error);
});

Important Notes

Document Processing: Both documents must have status: "processed" from List Documents API
Checkpoint Selection: Only checkpoints set to true will be analyzed and returned
Margin Units: Page margins are measured in inches
Response Order: Results always return in order: [Document 1, Document 2]
Page Numbering: Pages are numbered starting from "1" as string keys

Next Steps

After comparing document formats:

Analyze Differences: Review margin, link, and font size differences
Validate Results: Check if formatting meets your requirements
Generate Reports: Create formatting comparison reports
Take Action: Update documents based on comparison results

Need Help? Contact support at support@k-v.ai

Format Comparison

On this page