Tutorial: Converting to PDF Formats with Advanced Options

Learning Objectives

In this tutorial, you’ll learn how to:

Convert various document formats to PDF with GroupDocs.Conversion Cloud API
Configure advanced PDF options like resolution, compression, and security
Optimize PDF output for different business needs
Control page layout, bookmarks, and metadata
Implement PDF conversion across different programming languages
Solve common PDF conversion challenges

Prerequisites

Before starting this tutorial, you should have:

A GroupDocs.Conversion Cloud account (if you don’t have one, register for a free trial)
Your Client ID and Client Secret credentials
Basic understanding of REST API concepts
Familiarity with your preferred programming language (C#, Java, Python, PHP, Ruby, or Node.js)
Source documents for conversion (DOCX, XLSX, PPTX, images, etc.)

Why Convert to PDF Format?

PDF (Portable Document Format) has become the standard for document exchange and has several advantages:

Platform independence: Looks the same on any device or operating system
Visual fidelity: Preserves exact layout, fonts, and formatting
Security: Supports encryption, permissions, and digital signatures
File size optimization: Can be compressed without significant quality loss
Archiving: Ideal for long-term document storage
Ease of sharing: Widely accepted format in business environments

GroupDocs.Conversion Cloud API offers powerful capabilities to convert almost any document format to PDF with precise control over the output.

Implementation Steps

Step 1: Set Up Your Development Environment

First, ensure you have the GroupDocs.Conversion Cloud SDK installed for your language: For .NET:

Install-Package GroupDocs.Conversion-Cloud

For Java:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-conversion-cloud</artifactId>
    <version>latest-version</version>
</dependency>

For Python:

pip install groupdocs-conversion-cloud

Step 2: Authenticate with the API

To use GroupDocs.Conversion Cloud API, you need to authenticate using your Client ID and Client Secret:

// Initialize the API with your credentials
string MyClientId = "XXXX-XXXX-XXXX-XXXX"; // Your Client ID
string MyClientSecret = "XXXXXXXXXXXXXXXX"; // Your Client Secret
var configuration = new Configuration(MyClientId, MyClientSecret);
var apiInstance = new ConvertApi(configuration);

Step 3: Basic PDF Conversion

Let’s start with a basic conversion to PDF:

// Basic conversion to PDF
var settings = new ConvertSettings
{
    FilePath = "WordProcessing/sample.docx",
    Format = "pdf",
    OutputPath = "converted/basic.pdf"
}
var response = apiInstance.ConvertDocument(new ConvertDocumentRequest(settings));
Console.WriteLine("Document converted successfully: " + response[0].Url);

Step 4: Advanced PDF Conversion Options

Now, let’s explore advanced PDF options for greater control:

// Advanced PDF conversion with options
var pdfOptions = new PdfConvertOptions
{
    // Document layout options
    Dpi = 300,                  // Resolution in dots per inch
    Width = 800,                // Width in pixels
    Height = 1200,              // Height in pixels
    
    // Visual options
    Grayscale = false,          // Color or grayscale
    Zoom = 100,                 // Zoom level (100 = 100%)
    
    // Security options
    Password = "password123",   // Document password
    
    // Optimization options
    CompressImages = true,      // Compress images to reduce size
    ImageQuality = 95,          // Image quality (0-100)
    UnembedFonts = false,       // Keep fonts embedded
    
    // PDF-specific options
    BookmarksOutlineLevel = 2,  // Bookmarks visibility level
    CenterWindow = true,        // Center document in viewer
    DisplayDocTitle = true,     // Display document title
    FitWindow = true,           // Fit view to window
    
    // Page options
    FromPage = 1,               // Start page
    PagesCount = 5,             // Number of pages to convert
    
    // Cleanup options
    RemoveUnusedObjects = true, // Remove unused objects
    RemoveUnusedStreams = true, // Remove unused streams
};

var settings = new ConvertSettings
{
    FilePath = "WordProcessing/sample.docx",
    Format = "pdf",
    ConvertOptions = pdfOptions,
    OutputPath = "converted/advanced.pdf"
};

var response = apiInstance.ConvertDocument(new ConvertDocumentRequest(settings));
Console.WriteLine("Document converted with advanced options: " + response[0].Url);

Step 5: Password-Protected PDF Conversion

You can create password-protected PDFs for sensitive documents:

// Create password-protected PDF
var secureOptions = new PdfConvertOptions
{
    Password = "securePassword123", // Set document password
    // Additional security options
};

var settings = new ConvertSettings
{
    FilePath = "WordProcessing/sample.docx",
    Format = "pdf",
    ConvertOptions = secureOptions,
    OutputPath = "converted/secure.pdf"
};

var response = apiInstance.ConvertDocument(new ConvertDocumentRequest(settings));
Console.WriteLine("Secure PDF created: " + response[0].Url);

Step 6: PDF/A Compliance

For archival purposes, you can create PDF/A compliant files:

// Create PDF/A compliant document
var pdfaOptions = new PdfConvertOptions
{
    RemovePdfaCompliance = false, // Keep PDF/A compliance
    // Other options...
};

var settings = new ConvertSettings
{
    FilePath = "WordProcessing/sample.docx",
    Format = "pdf",
    ConvertOptions = pdfaOptions,
    OutputPath = "converted/pdfa.pdf"
};

var response = apiInstance.ConvertDocument(new ConvertDocumentRequest(settings));
Console.WriteLine("PDF/A document created: " + response[0].Url);

Complete Code Examples

Using C#

using System;
using System.Collections.Generic;
using GroupDocs.Conversion.Cloud.Sdk.Api;
using GroupDocs.Conversion.Cloud.Sdk.Client;
using GroupDocs.Conversion.Cloud.Sdk.Model;
using GroupDocs.Conversion.Cloud.Sdk.Model.Requests;

namespace GroupDocs.Conversion.Cloud.Examples
{
    class ConvertToPdfExample
    {
        public static void Run()
        {
            // Get your credentials from https://dashboard.groupdocs.cloud/applications
            string MyClientId = "XXXX-XXXX-XXXX-XXXX"; // Your Client ID
            string MyClientSecret = "XXXXXXXXXXXXXXXX"; // Your Client Secret
            
            var configuration = new Configuration(MyClientId, MyClientSecret);
            
            // Create necessary API instances
            var apiInstance = new ConvertApi(configuration);
            
            try
            {
                // Example 1: Basic PDF conversion
                var basicSettings = new ConvertSettings
                {
                    FilePath = "WordProcessing/sample.docx",
                    Format = "pdf",
                    OutputPath = "converted/basic.pdf"
                };
                
                var basicResponse = apiInstance.ConvertDocument(new ConvertDocumentRequest(basicSettings));
                Console.WriteLine("Basic conversion completed: " + basicResponse[0].Url);
                
                // Example 2: High-quality PDF with bookmarks
                var highQualityOptions = new PdfConvertOptions
                {
                    Dpi = 300,
                    BookmarksOutlineLevel = 3,
                    CompressImages = false,
                    ImageQuality = 100,
                    DisplayDocTitle = true
                };
                
                var highQualitySettings = new ConvertSettings
                {
                    FilePath = "WordProcessing/sample.docx",
                    Format = "pdf",
                    ConvertOptions = highQualityOptions,
                    OutputPath = "converted/high-quality.pdf"
                };
                
                var highQualityResponse = apiInstance.ConvertDocument(new ConvertDocumentRequest(highQualitySettings));
                Console.WriteLine("High-quality conversion completed: " + highQualityResponse[0].Url);
                
                // Example 3: Optimized PDF for web sharing
                var optimizedOptions = new PdfConvertOptions
                {
                    CompressImages = true,
                    ImageQuality = 75,
                    Linearize = true, // Optimized for web viewing
                    UnembedFonts = true,
                    RemoveUnusedObjects = true,
                    RemoveUnusedStreams = true
                };
                
                var optimizedSettings = new ConvertSettings
                {
                    FilePath = "WordProcessing/sample.docx",
                    Format = "pdf",
                    ConvertOptions = optimizedOptions,
                    OutputPath = "converted/optimized.pdf"
                };
                
                var optimizedResponse = apiInstance.ConvertDocument(new ConvertDocumentRequest(optimizedSettings));
                Console.WriteLine("Optimized conversion completed: " + optimizedResponse[0].Url);
                
                // Example 4: Secure PDF
                var secureOptions = new PdfConvertOptions
                {
                    Password = "securePassword123",
                    UnembedFonts = false,
                    CompressImages = true,
                    ImageQuality = 90
                };
                
                var secureSettings = new ConvertSettings
                {
                    FilePath = "WordProcessing/sample.docx",
                    Format = "pdf",
                    ConvertOptions = secureOptions,
                    OutputPath = "converted/secure.pdf"
                };
                
                var secureResponse = apiInstance.ConvertDocument(new ConvertDocumentRequest(secureSettings));
                Console.WriteLine("Secure PDF created: " + secureResponse[0].Url);
            }
            catch (Exception e)
            {
                Console.WriteLine("Exception when calling ConvertApi: " + e.Message);
            }
        }
    }
}

Using Python

# Import required modules
import groupdocs_conversion_cloud
import os

# Get your credentials from https://dashboard.groupdocs.cloud/applications
client_id = "XXXX-XXXX-XXXX-XXXX"  # Your Client ID
client_secret = "XXXXXXXXXXXXXXXX"  # Your Client Secret

# Create instance of the API
api = groupdocs_conversion_cloud.ConvertApi.from_keys(client_id, client_secret)

try:
    # Example 1: Basic PDF conversion
    basic_settings = groupdocs_conversion_cloud.ConvertSettings()
    basic_settings.file_path = "WordProcessing/sample.docx"
    basic_settings.format = "pdf"
    basic_settings.output_path = "converted/basic.pdf"
    
    basic_result = api.convert_document(groupdocs_conversion_cloud.ConvertDocumentRequest(basic_settings))
    print(f"Basic conversion completed: {basic_result[0].url}")
    
    # Example 2: High-quality PDF with bookmarks
    high_quality_options = groupdocs_conversion_cloud.PdfConvertOptions()
    high_quality_options.dpi = 300
    high_quality_options.bookmarks_outline_level = 3
    high_quality_options.compress_images = False
    high_quality_options.image_quality = 100
    high_quality_options.display_doc_title = True
    
    high_quality_settings = groupdocs_conversion_cloud.ConvertSettings()
    high_quality_settings.file_path = "WordProcessing/sample.docx"
    high_quality_settings.format = "pdf"
    high_quality_settings.convert_options = high_quality_options
    high_quality_settings.output_path = "converted/high-quality.pdf"
    
    high_quality_result = api.convert_document(groupdocs_conversion_cloud.ConvertDocumentRequest(high_quality_settings))
    print(f"High-quality conversion completed: {high_quality_result[0].url}")
    
    # Example 3: Optimized PDF for web sharing
    optimized_options = groupdocs_conversion_cloud.PdfConvertOptions()
    optimized_options.compress_images = True
    optimized_options.image_quality = 75
    optimized_options.linearize = True  # Optimized for web viewing
    optimized_options.unembed_fonts = True
    optimized_options.remove_unused_objects = True
    optimized_options.remove_unused_streams = True
    
    optimized_settings = groupdocs_conversion_cloud.ConvertSettings()
    optimized_settings.file_path = "WordProcessing/sample.docx"
    optimized_settings.format = "pdf"
    optimized_settings.convert_options = optimized_options
    optimized_settings.output_path = "converted/optimized.pdf"
    
    optimized_result = api.convert_document(groupdocs_conversion_cloud.ConvertDocumentRequest(optimized_settings))
    print(f"Optimized conversion completed: {optimized_result[0].url}")
    
    # Example 4: Grayscale PDF
    grayscale_options = groupdocs_conversion_cloud.PdfConvertOptions()
    grayscale_options.grayscale = True
    grayscale_options.dpi = 300
    
    grayscale_settings = groupdocs_conversion_cloud.ConvertSettings()
    grayscale_settings.file_path = "WordProcessing/sample.docx"
    grayscale_settings.format = "pdf"
    grayscale_settings.convert_options = grayscale_options
    grayscale_settings.output_path = "converted/grayscale.pdf"
    
    grayscale_result = api.convert_document(groupdocs_conversion_cloud.ConvertDocumentRequest(grayscale_settings))
    print(f"Grayscale conversion completed: {grayscale_result[0].url}")

except groupdocs_conversion_cloud.ApiException as e:
    print(f"Exception when calling ConvertApi: {e}")

Using cURL

# First get JSON Web Token
curl -v "https://api.groupdocs.cloud/connect/token" \
-X POST \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json"

# Get token from JSON response
# Now use the token to convert document with advanced PDF options
curl -v "https://api.groupdocs.cloud/v2.0/conversion" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-d "{
    'FilePath': 'WordProcessing/sample.docx',
    'Format': 'pdf',
    'ConvertOptions': {
        'Dpi': 300,
        'Width': 800,
        'Height': 1200,
        'BookmarksOutlineLevel': 2,
        'CenterWindow': true,
        'CompressImages': true,
        'DisplayDocTitle': true,
        'FitWindow': true,
        'FromPage': 1,
        'PagesCount': 5,
        'Grayscale': false,
        'ImageQuality': 95,
        'LinearizeDocument': true,
        'Zoom': 100
    },
    'OutputPath': 'converted/advanced.pdf'
}"

PDF Conversion Use Cases

Use Case 1: High-Quality Archival Documents

For organizations that need to archive important documents with maximum fidelity and compliance:

var archivalOptions = new PdfConvertOptions
{
    Dpi = 300,                    // High resolution
    CompressImages = false,       // No image compression
    ImageQuality = 100,           // Maximum quality
    RemovePdfaCompliance = false, // Maintain PDF/A compliance
    Grayscale = false,            // Keep color information
    BookmarksOutlineLevel = 3     // Include detailed bookmarks
};

Use Case 2: Web-Optimized Documents

For documents that will be distributed online where file size matters:

var webOptions = new PdfConvertOptions
{
    CompressImages = true,        // Compress images
    ImageQuality = 75,            // Lower quality is smaller
    Dpi = 150,                    // Lower resolution is smaller
    UnembedFonts = true,          // Remove embedded fonts
    RemoveUnusedObjects = true,   // Clean up unused objects
    RemoveUnusedStreams = true,   // Clean up unused streams
    Linearize = true              // Optimize for web viewing
};

Use Case 3: Secure Confidential Documents

For sensitive documents that need protection:

var secureOptions = new PdfConvertOptions
{
    Password = "StrongPassword123!", // Document password
    UnembedFonts = false,            // Keep fonts embedded for fidelity
    Grayscale = false,               // Keep color information
    ImageQuality = 90                // Good quality without excessive size
};

Advanced PDF Features Explanation

The BookmarksOutlineLevel option controls how document headings are converted to PDF bookmarks:

Value 0: No bookmarks are created
Value 1: Only the highest level headings become bookmarks
Value 2+: More detailed heading levels are included as nested bookmarks

PDF Optimization

These options help reduce file size:

CompressImages: Enables image compression
ImageQuality: Sets compression quality (lower values = smaller files)
UnembedFonts: Removes embedded fonts to reduce size
RemoveUnusedObjects/Streams: Cleans up unnecessary data

PDF/A Compliance

PDF/A is an ISO-standardized version for long-term archiving:

RemovePdfaCompliance: When set to false, maintains PDF/A compatibility

Troubleshooting Tips

Large File Sizes

Issue: The converted PDF is too large.Solution:

Enable CompressImages and reduce ImageQuality
Set UnembedFonts to true if font fidelity is not critical
Enable RemoveUnusedObjects and RemoveUnusedStreams
Consider reducing the Dpi value

Missing Bookmarks

Issue: PDF doesn’t contain the expected bookmarks.Solution:

Ensure the source document has proper heading styles
Increase the BookmarksOutlineLevel value
Check if the source document format supports heading extraction

Font Issues

Issue: Text appears with incorrect fonts in the PDF.Solution:

Set UnembedFonts to false
Provide custom fonts via the FontsPath property
Use standard fonts like Arial or Times New Roman in the source document

Try It Yourself

Now that you’ve learned about PDF conversion options, try these exercises:

Convert a document to a small, web-optimized PDF
Create a high-quality PDF with full bookmarks for archiving
Convert a document to grayscale PDF for printing
Create a password-protected PDF with custom security settings

What You’ve Learned

In this tutorial, you’ve learned how to:

Convert various document formats to PDF using GroupDocs.Conversion Cloud API
Configure advanced PDF options for different business requirements
Optimize PDF output for web, print, or archiving purposes
Control security features like password protection
Manage document appearance including resolution and color mode
Troubleshoot common PDF conversion issues

Next Steps

Now that you know how to create customized PDFs, you might want to explore:

Helpful Resources

If you have questions about this tutorial, please feel free to post them in our support forum.;