PDFen Logo

API Changes & Migration Guide

Full backwards compatibility maintained while introducing modern improvements

Overview

PDFen.com is upgrading to a new, modern platform while maintaining full backwards compatibility with existing API integrations. This guide explains what's changing, what stays the same, and how to take advantage of new features.

Key Points

  • ⚠️ v1 API will be shut down on June 1, 2026 - All users must migrate to v2

  • ⚠️ New users can only use v2 API - v1 is only for existing integrations

  • ✅ Your existing code will continue to work until June 1, 2026 - v1 API remains fully compatible

  • ✅ Migrate before June 1, 2026 - After this date, only v2 API will be available

  • ✅ New v2 API available now - simplified, modern approach

  • ✅ More conversion options - expanded functionality for all users

Action You Need to Take

To prepare for the migration, please complete these steps:

  • 1. Review the documentation - Read the v1 API docs and v2 API docs to understand the differences

  • 2. Get your API token - Generate an API token in your profile (required for v2, recommended for v1)

  • 3. Link legacy templates (if applicable) - If you use custom templates, log in after mid-December 2025 and link your old template ID to a new cover page in the Profile section

  • 4. Test with v2 API - Start testing your integration with v2 API using the same conversion options

  • 5. Update authentication - Switch from username/password to API token authentication before month 6

  • 6. Complete migration - Fully migrate to v2 API before June 1, 2026 when v1 will be shut down

New Platform Architecture

We've rebuilt PDFen.com on a modern Laravel platform with: - Improved performance and reliability - Enhanced security - More conversion options - Better error handling - Real-time conversion status updates

API Versions

**v1 API (Legacy - Being Deprecated)** - Endpoint: `https://www.pdfen.com/api/v1/` - 🚀 **Available from 29-December 2025 on rebuild website** (new website launch) - ⚠️ **Will be shut down on June 1, 2026** - Only available for existing users (created before December 2025) - New users cannot access v1 API - Fully backwards compatible until shutdown date - Same request/response formats - All existing endpoints supported **v2 API (Current - Required for All New Users)** - Endpoint: `https://www.pdfen.com/api/v2/` - 🚀 **Launches mid-December 2025** with new website - ✅ **Only API version available after June 1, 2026** - Required for all new users (from 29 December 2025 onwards) - Simplified workflow - API token authentication (required) - Direct conversion approach (no sessions required) - Enhanced error messages - Real-time status tracking

Authentication Changes

**Current Authentication Methods:** 1. **Username/Password** (Legacy - Being Deprecated) - Currently supported for backwards compatibility - Will be disabled after 6 months - Not recommended for new integrations 2. **API Tokens** (Recommended) - Available now for both v1 and v2 APIs - More secure than username/password - Easy to manage in your profile - Can be regenerated without changing password **Deprecation Timeline:** - ✅ **Now - Month 3**: Both methods supported - ⚠️ **Month 3 - Month 6**: Deprecation warnings in responses - ❌ **After Month 6**: Username/password disabled

Getting Your API Token

1. Log in to your PDFen account 2. Go to your Profile → API Tokens 3. Click "Create New Token" 4. Give it a descriptive name 5. Copy the token (shown only once!) 6. Store it securely **v1 API with token:** ```bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST https://www.pdfen.com/api/v1/sessions ``` **v2 API (token required):** ```bash curl -H "Authorization: Bearer YOUR_API_TOKEN" \ -X POST https://www.pdfen.com/api/v2/convert \ -F "file=@document.pdf" \ -F "output_format=pdfa-2b" ```

Backwards Compatibility

All existing endpoints remain functional: - `POST /sessions` - Create session (now also accepts API token) - `GET /sessions/{id}` - Get session info - `POST /sessions/{id}/files` - Upload files - `PUT /sessions/{id}/files/{id}/data` - Upload file data - `PATCH /sessions/{id}/options` - Set conversion options - `GET /sessions/{id}/templates` - List templates - `POST /sessions/{id}/processes` - Start conversion - `GET /download` - Download result

Feature Support Matrix

✅ **Fully Supported:** - PDF/A conversion (1A, 1B, 2A, 2B, 3A, 3B) - OCR with multiple languages - Image compression (web, print, custom) - PDF merging vs batch processing - File ordering - URL-based uploads - Partial uploads - Async and sync processing - Session copying - Custom headers and footers (via cover page) - Table of contents generation (via cover page) - PDF bookmarks (via cover page) ⚠️ **Limited Support:** - **Templates**: Cover page templates with legacy template linking - Users can create 1 cover page template per account (vs unlimited in legacy) - Legacy template_id can be linked to new cover page via UI dropdown - API v1 calls with template_id continue to work (no code changes needed) - Custom fonts and colors not available (professional defaults used) - Template linking only shown to users with legacy templates (pdfen_pdfenc_templates) - **Chapters**: Accepted but ignored (files processed in order) ❌ **Not Supported:** - Multiple cover page templates per user - Custom fonts and color schemes - Advanced template layouts from legacy system

Supported Conversion Options

**PDF Type Selection:** ```json { "pdftype": "normal|1A|1B|2A|2B|3A|3B" } ``` **OCR Options:** ```json { "ocr": true, "ocrlanguage": "Dutch|English|German|French|Italian|Spanish|Portuguese" } ``` **Compression:** ```json { "compress": "none|small|web|printing", "postprocessing_compress_images_quality": 85, "postprocessing_compress_images_dpi": 150, "postprocessing_compress_fonts": true, "postprocessing_imagecolors": "printing|web|small" } ``` **Post-Processing:** ```json { "postprocessing_linearize": true, "postprocessing_strip_meta": false, "postprocessing_strip_interactive_elements": false, "postprocessing_compress_misc": true } ```

Migration Timeline

**Mid-December 2025:** - 🚀 New website goes live with v2 API - ✅ v1 API remains functional for existing users only - ✅ v2 API available for all users - ✅ API token authentication available - ⚠️ New users (registered after December 2025) can only use v2 API **Late December 2025:** - 📧 Email notification to all API users about v1 deprecation - 📚 SDK updates released for v2 **Month 3 (February 2026):** - ⚠️ Deprecation warnings in v1 API responses - 📧 Reminder emails sent to migrate to v2 **Month 6 (May 2026):** - ⚠️ Final migration warning emails - 📚 Migration support available **June 1, 2026:** - ❌ v1 API will be shut down completely - ✅ Only v2 API available - ✅ All users must migrate to v2 before this date

Testing Your Integration

Before migrating to production: - [ ] Test with API token authentication - [ ] Verify all conversion options work - [ ] Test error scenarios - [ ] Check warning messages - [ ] Validate output files - [ ] Test rate limits - [ ] Review logs for deprecation notices **Sandbox Environment:** ``` https://sandbox.pdfen.com/api/v1/ https://sandbox.pdfen.com/api/v2/ ``` **Sandbox features:** - Free testing (no credits consumed) - Isolated from production data - Same API endpoints - Faster processing (smaller queue)

Rate Limits

**Free Users:** - v1 API: 100 requests/hour - v2 API: 100 requests/hour **Paid Users:** - v1 API: 1,000 requests/hour - v2 API: 1,000 requests/hour Rate limit headers: ``` X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 950 X-RateLimit-Reset: 1234567890 ```

Credits and Pricing

**Credit Usage:** Both v1 and v2 APIs use the same credit system. Credits are consumed based on the conversion type and number of files processed. **Standard Conversions:** - Most conversions: 1 credit per document - PDF/A conversion: 1 credit - OCR processing: 1 credit per document - Compression: included (no extra charge) **Email to PDF - Special Pricing:** Email-to-PDF conversions use intelligent per-email pricing: | Component | Credits | Notes | |-----------|---------|-------| | Email body | 1 credit | Per email | | Office attachments | 1 credit each | DOCX, XLSX, PPTX, etc. | | PDF/Image attachments | FREE | Direct inclusion | | Merge operation | 1 credit | Only if email produces >1 PDF | **Email-to-PDF Examples:** - 1 email, no attachments: **1 credit** - 1 email, 1 DOCX: **3 credits** (1 body + 1 office + 1 merge) - 1 email, 2 images: **2 credits** (1 body + 1 merge) - 10 emails, 10 DOCX (1 each): **30 credits** (10 bodies + 10 office + 10 merges) **Organization Credits (NEW):** The new system supports organization credit pools. If you're a member of an organization: - Credits are automatically charged from your organization's pool first - If organization credits are depleted, your personal credits are used - API responses include `credits_source` field showing where credits were charged - This is automatic and requires no changes to your API calls **Credits Response:** All process results include credit information: ```json { "credits": 5, "credits_left": 95, "credits_explain": "5 credits charged for conversion", "credits_source": "organization", "credits_source_name": "Your Company Inc" } ``` Note: `credits_source` and `credits_source_name` fields are available in both v1 and v2 APIs.

Migrating Your Templates

**If you currently use templates via the API:** The new system includes a seamless template migration feature for existing customers. **Automatic Migration (For Existing Template Users):** If you have templates in the legacy system (pdfen_pdfenc_templates), you can link them to new cover pages: 1. After the new website launches (mid-December 2025), log in to your account 2. Navigate to Profile → Cover Page Templates 3. Create a new cover page template 4. In the "API v1 Legacy Compatibility" section, select your old template ID from the dropdown 5. Configure your headers, footers, and table of contents 6. Save the template **Your API v1 calls continue to work:** - Keep using the same `template_id` in your API calls - The system automatically finds your linked cover page - No changes needed to your existing code - Full backwards compatibility maintained **Manual Migration (Optional - For Better Results):** While your old template_id keeps working, you can optionally: - Recreate your template design in the new cover page UI - Take advantage of improved table of contents generation - Use the modern cover page designer **What's preserved:** - Your legacy template ID (automatically linked) - Basic conversion settings (PDF type, OCR, compression) - API v1 compatibility (no code changes needed) **What's improved:** - Modern cover page designer - Better table of contents generation - Improved PDF bookmark structure **Limitations:** - 1 cover page template per account (vs unlimited in legacy system) - Custom fonts and colors not available (professional defaults used) - Some advanced legacy layout features not supported **No template users:** If you don't use templates (template_id = 174 or no template), no action needed. Your conversions continue to work without changes.

Getting Help

**Documentation:** - [API v1 Documentation](/api/docs/v1) - Complete v1 API reference - [API v2 Documentation](/api/docs/v2) - Modern v2 API reference - [API Documentation Index](/api/docs) - Overview and guides - [Developers Section](/developers) - Main developers portal **Support:** - **Email**: [contact@pdfen.com](mailto:contact@pdfen.com) - **Documentation**: Browse our [comprehensive docs](/api/docs) - **Migration Help**: Dedicated support available for API migration

Frequently Asked Questions

Everything you need to know about the API migration and new features.

When will the v1 API be shut down?

The v1 API will be completely shut down on June 1, 2026. After this date, only the v2 API will be available. All users must migrate to v2 before this deadline.

I'm a new user - can I use the v1 API?

No. New users registered after December 2025 can only use the v2 API. The v1 API is only available for existing integrations to provide a smooth migration period.

Will my existing integration break during the migration?

Your v1 API integration will continue to work until June 1, 2026. We recommend starting your migration to v2 as soon as possible to avoid any last-minute issues.

What features am I losing when migrating to v2?

Most functionality is preserved. You lose: session-based workflow (v2 uses direct conversion), custom page layouts, chapter structures, and multiple user-defined templates. But you gain: simpler API, more conversion options, better performance, enhanced error handling, and real-time status updates.

Can I use both v1 and v2 APIs simultaneously?

Yes, but only if you are an existing user. You can use v1 until June 1, 2026, while gradually migrating to v2. New users (registered after December 2025) can only use v2.

How do I authenticate with the API?

The API uses Bearer token authentication. Go to Profile → API Tokens to generate a token, then include it in the Authorization header: Authorization: Bearer YOUR_TOKEN. Important: copy the token immediately after creation - it's only shown once! The old username/password authentication is deprecated and will stop working on June 1, 2026.

Are there rate limits on API requests?

Yes, the API has the following limits: 60 requests per minute, maximum 200 files per request (up to 500MB total depending on license), and 5 concurrent conversions per user. Consult our pricing page to review exact bulk conversion and file size limits for each subscription tier.

How do organization credits work with the API?

If you are a member of an organization, API requests will automatically use the organization credit pool first. If the organization runs out of credits, the system will fall back to your personal credits. The API response includes information about which credit source was used.

How do I start a conversion via the API?

Use the POST /api/v2/convert endpoint with your files and workflow ID. First, get available workflows via GET /api/v2/user/workflows, then submit your files as multipart/form-data with the workflow_id parameter. Set async=true for background processing, then poll the status endpoint until completion. See our API documentation for complete examples.

What conversion types does the API support?

The API supports a wide range of conversions: To PDF: Word, Excel, PowerPoint, images, HTML, email (EML/MSG), AutoCAD, eBooks, CSV, Markdown. From PDF: Word, Excel, PowerPoint, images (JPG/PNG/WebP), text, HTML, CSV. PDF Operations: merge, split, rotate, compress, protect/unprotect, OCR, PDF/A conversion, and repair. Use GET /api/v2/user/workflows to see all available conversion workflows.

What are the file size limits for API uploads?

API file limits depend on your chosen license. Consult our pricing page for the current plans that are on offer.

How do I check the status of my conversion?

After starting a conversion with async=true, use GET /api/v2/executions/{execution_id} to check the status. The response includes the current status (queued, processing, completed, failed) and progress information. Once completed, use GET /api/v2/executions/{execution_id}/download to retrieve the result.

Where can I find the complete API documentation?

Complete API documentation is available at pdfen.com/api/docs. This includes interactive Swagger UI for testing endpoints, detailed parameter descriptions, code examples in multiple languages (PHP, Python, JavaScript), and the OpenAPI specification for generating client libraries.

Are there official SDKs or client libraries available?

Yes, we offer an official PHP SDK that simplifies API integration: composer require pdfen/php-sdk. The SDK handles authentication, file uploads, status polling, and error handling automatically. More SDKs (Python, JavaScript) are coming soon. See the SDK documentation for usage examples.