API Documentation

Complete guide to integrating Makhtoom's document verification APIs into your applications.

Getting Started

Privacy First: We do not store your PDF files. Documents are processed in real-time and immediately discarded after stamping.

Makhtoom provides a simple way to stamp and verify PDF documents. Follow these steps to get started with the web interface:

1Upload your PDF document using drag & drop or the file picker
2Configure QR code position, hash algorithm, and company name
3Download your stamped PDF with the verification QR code

Verification Process

When a document is stamped, Makhtoom generates a unique cryptographic hash and embeds it in a QR code. This allows anyone to verify the document's authenticity.

1A SHA-256 or MD5 hash is computed from the stamped PDF content
2The hash and metadata are stored with a unique document ID (UUID)
3The QR code links to the verification page where users can upload the PDF to check authenticity

Verification Results

When verifying a document, the system compares the uploaded PDF's hash against the stored hash.

Authentic

The document hash matches the original. The file has not been modified since stamping.

Tampered

The document hash does not match. The file may have been altered after stamping.

API Key Authentication

To use the B2B API endpoints, you need to generate an API key from your profile page. API keys provide secure, programmatic access to Makhtoom's services.

API Key Format

mk_live_<user-prefix>_<random-32-chars>

Example: mk_live_98QaXW_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Generate API keys from your profile page after logging in. The full key is shown only once upon creation.

B2B API Reference

Use these endpoints to integrate document stamping and verification into your applications. All B2B endpoints require an API key passed via the X-API-Key header.

Stamp Document

POST/api/v1/stampX-API-Key

Stamp a PDF document with a verification QR code. Returns the stamped PDF as base64.

Parameters

Parameter	Type	Required	Description
pdfFile	File	Yes	The PDF file to stamp (multipart/form-data)
companyName	String	Yes	Company name to display on the QR code stamp
hashAlgorithm	String	No	Hash algorithm: 'sha256' (default) or 'md5'

Response

1{
2  "success": true,
3  "uid": "550e8400-e29b-41d4-a716-446655440000",
4  "verificationUrl": "https://makhtoom.com/verify/550e8400...",
5  "verificationId": "550E-8400-E29B-41D4",
6  "processedAt": "2024-01-20T10:30:00Z",
7  "fileSize": 125000,
8  "hash": "a1b2c3d4e5f6...",
9  "hashAlgorithm": "sha256",
10  "stampedPdfBase64": "JVBERi0xLjQKJ...",
11  "mimeType": "application/pdf"
12}

Verify Document

POST/api/v1/verify?uid={documentUid}X-API-Key

Verify a stamped PDF document against the stored hash. Returns authenticity status.

Parameters

Parameter	Type	Required	Description
uid	String (query)	Yes	The document UID returned from the stamp endpoint
pdfFile	File	Yes	The stamped PDF file to verify

Response

1{
2  "authentic": true,
3  "message": "File is Authentic",
4  "details": {
5    "documentUid": "550e8400-e29b-41d4-a716-446655440000",
6    "companyName": "Your Company",
7    "timestamp": "2024-01-20T10:30:00Z",
8    "hashAlgorithm": "sha256",
9    "fileSize": 125000
10  }
11}

Account Status

GET/api/v1/statusX-API-Key

Get your subscription status, usage statistics, and API key information.

Response

1{
2  "subscription": {
3    "status": "active",
4    "planType": "Pro",
5    "interval": "month",
6    "expiresAt": "2024-02-20T10:30:00Z"
7  },
8  "usage": {
9    "currentMonth": 45,
10    "totalProcessed": 1250,
11    "lastProcessed": "2024-01-20T10:30:00Z"
12  },
13  "limits": {
14    "monthlyDocuments": 1000,
15    "remaining": 955
16  },
17  "apiKey": {
18    "keyId": "abc123",
19    "name": "Production Key",
20    "usageStats": { "requests": 150, "stamped": 45, "verified": 105 }
21  }
22}

Code Examples

Here are examples showing how to use the Makhtoom API in different languages.

Stamp a Document

1curl -X POST https://makhtoom.com/api/v1/stamp \
2  -H "X-API-Key: mk_live_98QaXW_a1b2c3d4e5f6g7h8i9j0..." \
3  -F "pdfFile=@document.pdf" \
4  -F "companyName=Your Company" \
5  -F "hashAlgorithm=sha256"

Verify a Document

1curl -X POST "https://makhtoom.com/api/v1/verify?uid=550e8400-e29b-41d4-a716-446655440000" \
2  -H "X-API-Key: mk_live_98QaXW_a1b2c3d4e5f6g7h8i9j0..." \
3  -F "pdfFile=@stamped-document.pdf"

Check Account Status

1curl https://makhtoom.com/api/v1/status \
2  -H "X-API-Key: mk_live_98QaXW_a1b2c3d4e5f6g7h8i9j0..."

QR Code Positioning

Choose where the verification QR code appears on your documents. You can customize which pages receive the stamp and where it is positioned.

Page Selection

All Pages

Stamp every page in the document

Single Page

Stamp only the first or last page

Vertical Position

Top

Bottom

Horizontal Position

Left

Center

Right

Frequently Asked Questions

What file types are supported?

Currently, we support PDF documents only. All files are processed securely and are never stored on our servers after processing.

How secure is the verification?

We use SHA-256 cryptographic hashing to ensure document integrity. Any modification to the document, even a single byte, will result in a completely different hash and fail verification.

What are the API rate limits?

Rate limits depend on your subscription plan. Basic plans allow 100 documents/month, Pro plans allow 1,000 documents/month, and Enterprise plans have custom limits. API requests are limited to 30 per minute.

Can I use the API in production?

Yes! The API is production-ready. Generate an API key from your profile page, and use the /api/v1/ endpoints with your key in the X-API-Key header.

Quick Navigation

Getting Started
Verification Process
Verification Results
API Key Authentication
B2B API Reference
Code Examples
QR Code Positioning
Frequently Asked Questions

Need Help?

Our support team is ready to help you integrate Makhtoom into your workflow.

Contact Support