📖 Overview
Welcome to PDF Stamper! Our service allows you to add custom text stamps and watermarks to your PDF documents with professional results.
Key Features
- Add up to 2 lines of custom text plus diagonal watermark
- 6 position options (top/bottom, left/center/right)
- Customizable font size, color, and opacity
- Optional password protection for PDFs
- Support for both file upload and URL-based processing
- RESTful API for programmatic access
- Credit-based billing system
💡 Credit System: Our service uses a credit-based system where 1 credit processes up to 5 pages. For example, a 12-page PDF would use 3 credits (6-10 pages = 2 credits, 11-15 pages = 3 credits).
🔌 API Documentation
Getting Started
To use the API, you need an API key. Please register and log in to get your API key.
Endpoint
POST https://pdfstamping.com/api.php
Authentication
Include your API key in the request header:
X-API-Key: sk_live_your_api_key_here
Request Parameters
| Parameter |
Type |
Required |
Description |
pdf_file |
File |
One of* |
PDF file to process (upload) |
pdf_url |
String |
One of* |
URL to PDF file (supports direct URLs, Google Drive, Dropbox) |
text1 |
String |
No |
First line of text to stamp |
text2 |
String |
No |
Second line of text to stamp |
diagonal_text |
String |
No |
Diagonal watermark text |
position |
String |
No |
Position: top_left, top_center, top_right, bottom_left, bottom_center, bottom_right (default: top_center) |
diagonal_opacity |
Float |
No |
Opacity for diagonal watermark (0.0 to 1.0, default: 0.3) |
font_size |
Integer |
No |
Font size in points (6-72, default: 9) |
text_color |
String |
No |
Hex color code (default: #666666) |
password_protect |
Boolean |
No |
Enable PDF password protection (default: true) |
response_type |
String |
No |
Response format: base64 or url (default: base64) |
* You must provide either pdf_file OR pdf_url, not both.
Example: cURL Request (File Upload)
curl -X POST "https://pdfstamping.com/api.php" \
-H "X-API-Key: sk_live_your_api_key_here" \
-F "pdf_file=@document.pdf" \
-F "text1=John Doe" \
-F "text2=john@example.com" \
-F "diagonal_text=CONFIDENTIAL" \
-F "position=top_center" \
-F "diagonal_opacity=0.3" \
-F "font_size=10" \
-F "text_color=#333333" \
-F "password_protect=true" \
-F "response_type=url"
Example: cURL Request (URL-based)
curl -X POST "https://pdfstamping.com/api.php" \
-H "X-API-Key: sk_live_your_api_key_here" \
-F "pdf_url=https://example.com/document.pdf" \
-F "text1=Jane Smith" \
-F "text2=jane@example.com" \
-F "response_type=base64"
Response Format (base64)
{
"success": true,
"data": {
"pdf_base64": "JVBERi0xLjQK...",
"pages_processed": 4,
"credits_used": 1,
"credits_remaining": 310,
"filename": "stamped_document_20260121_143020.pdf"
},
"meta": {
"api_version": "1.0",
"timestamp": "2026-01-21T14:30:20+00:00"
}
}
Response Format (url)
{
"success": true,
"data": {
"download_url": "https://pdfstamping.com/download.php?id=abc123",
"expires_at": "2026-01-22T14:30:20+00:00",
"pages_processed": 4,
"credits_used": 1,
"credits_remaining": 310,
"filename": "document_20260121_143020.pdf"
},
"meta": {
"api_version": "1.0",
"timestamp": "2026-01-21T14:30:20+00:00"
}
}
⚠️ Important: Download URLs expire after 24 hours and are single-use only. Make sure to download the file promptly.
Error Responses
{
"success": false,
"error": {
"message": "Insufficient credits",
"code": 402,
"details": {
"required": 2,
"available": 0
}
}
}
Error Codes
| Code |
Meaning |
Description |
| 400 |
Bad Request |
Invalid parameters or missing required fields |
| 401 |
Unauthorized |
Invalid or missing API key |
| 402 |
Payment Required |
Insufficient credits to process request |
| 403 |
Forbidden |
Account disabled - contact support |
| 405 |
Method Not Allowed |
Only POST requests are accepted |
| 500 |
Internal Server Error |
Server error during processing |
🖥️ Web Interface Help
Getting Started
- Create an Account: Click "Register" to create your free account
- Purchase Credits: Buy credit packages from the "Buy Credits" page
- Upload PDF: Use the web interface to upload your PDF file
- Add Text: Enter your custom text and choose position
- Download: Click "Stamp PDF" and download your stamped document
Using the Stamper
How do I add text to my PDF?
Simply fill in the "Text Line 1" and/or "Text Line 2" fields. You can also add a diagonal watermark in the "Diagonal Text" field.
How do I choose where the text appears?
Use the "Position" dropdown to select from 6 options: top-left, top-center, top-right, bottom-left, bottom-center, or bottom-right.
Can I customize the appearance?
Yes! You can adjust the font size (6-72 points), text color (using hex codes like #FF0000), and diagonal watermark opacity (0.0 to 1.0).
What about password protection?
By default, processed PDFs are password-protected. The password will be displayed after processing. You can disable this by unchecking the "Password Protect PDF" option.
Dashboard Features
- View Credit Balance: See your available credits at a glance
- API Key Access: Copy your API key for programmatic access
- Purchase History: Review all your credit purchases
- API Activity: Monitor your API usage and processed files
- Credit Transactions: Track all credit additions and deductions
❓ Frequently Asked Questions
General Questions
How much does it cost?
We use a credit-based system. Credits never expire and can be used at your convenience:
- 100 credits for $10
- 275 credits for $25 (best value per credit)
- 600 credits for $50
- 1,300 credits for $100
Remember: 1 credit processes up to 5 pages.
How many credits do I need?
Credits are calculated based on pages: 1 credit per 5 pages (rounded up).
- 1-5 pages = 1 credit
- 6-10 pages = 2 credits
- 11-15 pages = 3 credits
- 16-20 pages = 4 credits
Do credits expire?
No! Your credits never expire. You can use them whenever you need to process PDFs.
Can I test the service before purchasing credits?
Yes! You can test in two ways:
The web interface is perfect for trying out the stamping features before committing to API integration.
What file formats are supported?
Currently, we only support PDF files. The maximum file size is 10MB per upload.
Can I use URLs instead of uploading files?
Yes! When using the API, you can provide a pdf_url parameter instead of uploading a file. We support direct URLs, Google Drive shared links, and Dropbox shared links.
Technical Questions
How do I get my API key?
After you
register and log in, your API key will be displayed on your dashboard.
What programming languages can I use with the API?
Our API is language-agnostic and works with any language that can make HTTP POST requests. Common choices include PHP, Python, JavaScript/Node.js, Ruby, Java, and C#.
Is there a rate limit on the API?
Currently, there are no hard rate limits. However, we monitor for unusual activity. If you need to process large volumes, please contact us to discuss your use case.
Can I use special characters or Unicode text?
Yes! We support Unicode characters including Cyrillic, Chinese, Japanese, Arabic, and other international character sets.
What happens to my files?
We process your files and immediately delete them from our servers. When using the "url" response type, temporary download files are automatically deleted after 24 hours or after being downloaded once, whichever comes first.
Account & Billing
What payment methods do you accept?
We use Stripe for secure payment processing and accept all major credit cards (Visa, MasterCard, American Express, Discover) as well as various digital wallets.
What is your refund policy?
All credit purchases are final and non-refundable. We recommend testing the service using the free web interface before purchasing credits to ensure it meets your needs.
How can I track my usage?
Your dashboard provides complete visibility into your credit balance, purchase history, and API activity. You can see exactly when credits were used and for which files.
Troubleshooting
I'm getting a 401 Unauthorized error
This means your API key is invalid or missing. Double-check that you're including the X-API-Key header with your correct API key from your dashboard.
I'm getting a 402 Payment Required error
You don't have enough credits to process the request. Check your credit balance on your dashboard and purchase more credits if needed.
The processed PDF looks different than expected
Check your parameters: font size (6-72), text color (hex format like #333333), position (must match one of the 6 valid options), and diagonal opacity (0.0 to 1.0).
My download link expired
Download URLs expire after 24 hours and are single-use only. If your link has expired, you'll need to process the PDF again. Consider using the base64 response type if you need to store the result long-term.